|
|
| Line 1: |
Line 1: |
| __TOC__
| | ==Introduction== |
|
| |
|
| CMake version tracking and development is hosted by [http://git-scm.com Git]. | | CMake version tracking and development is hosted by [http://git-scm.com Git]. |
| | Please select a task for further instructions: |
|
| |
|
| =Official Repository=
| | {|border="0" |
| | |
| One may browse the repository online using the [http://git.wiki.kernel.org/index.php/Gitweb Gitweb] interface at http://cmake.org/gitweb.
| |
| | |
| At the time of this writing the repository does not have branches and tags older than CMake 2.4.
| |
| Conversion of older branches and tags from CVS will be completed later and added. The release branches in CVS are represented in git as tags. To see the available tags and branches use git show-ref. The current release being worked on will be the release branch.
| |
| | |
| ==Cloning==
| |
| | |
| One may clone the repository using [http://www.kernel.org/pub/software/scm/git/docs/git-clone.html git clone] through the native <code>git</code> protocol:
| |
| | |
| $ git clone git://cmake.org/cmake.git CMake
| |
| | |
| or through the (less efficient) <code>http</code> protocol:
| |
| | |
| $ git clone http://cmake.org/cmake.git CMake
| |
| | |
| All further commands work inside the local copy of the repository created by the clone:
| |
| | |
| $ cd CMake
| |
| | |
| ==Branches==
| |
| | |
| We use a topic-based workflow as documented [http://public.kitware.com/Wiki/Git/Workflow/Topic here] and thus define integration branches:
| |
| | |
| * '''maint''': Release maintenance; bug fixes only
| |
| * '''master''': Release preparation; starting point for new features (default)
| |
| * '''next''': Development; new features published here first
| |
| | |
| We also provide additional branches:
| |
| | |
| * '''nightly''': Follows '''next''', updated at 01:00 UTC
| |
| * '''nightly-master''': Follows '''master''', updated at 01:00 UTC
| |
| * '''release''': Latest release or release candidate.
| |
| * '''dashboard''': Dashboard script (see [[#Dashboard|below]])
| |
| * '''hooks''': Local commit hooks ([[Git/Hooks#Local|place]] in .git/hooks)
| |
| | |
| After cloning, create a local branch to track the upstream branch using [http://www.kernel.org/pub/software/scm/git/docs/git-checkout.html git checkout]:
| |
| | |
| $ git checkout -b release origin/release
| |
| | |
| As a shortcut with Git >= 1.6.5 one may choose a branch during the initial clone:
| |
| | |
| $ git clone -b release git://cmake.org/cmake.git CMakeRel
| |
| | |
| ==Updating==
| |
| | |
| Use [http://www.kernel.org/pub/software/scm/git/docs/git-pull.html git pull] to update your repository and work tree with the latest upstream changes:
| |
| | |
| $ git checkout master
| |
| $ git pull
| |
| From git://cmake.org/cmake
| |
| 689aa0e..4803630 master -> origin/master
| |
| Updating 689aa0e..4803630
| |
| Fast forward
| |
| ...
| |
| | |
| Note the "Fast forward" in the output.
| |
| This assumes that you have made no local commits on master.
| |
| | |
| =Development=
| |
| | |
| We provide here a brief introduction to '''CMake''' development with Git.
| |
| See the [[Git/Resources|Resources]] page for further information such as Git tutorials.
| |
| | |
| First, use [http://www.kernel.org/pub/software/scm/git/docs/git-config.html git config] to introduce yourself to Git:
| |
| | |
| $ git config --global user.name "Your Name"
| |
| $ git config --global user.email "you@yourdomain.com"
| |
| | |
| Optionally enable color output from Git commands:
| |
| | |
| $ git config --global color.ui auto
| |
| | |
| The <code>--global</code> option stores the configuration settings in <code>~/.gitconfig</code> in your home directory so that they apply to all repositories.
| |
| | |
| ==Committing==
| |
| | |
| After cloning the repository using the above instructions one may commit new changes locally.
| |
| Follow our [http://public.kitware.com/Wiki/Git/Workflow/Topic workflow] instructions to commit on a local branch.
| |
| Here we document basic command-line usage.
| |
| Refer to Git documentation and other online tutorials for details.
| |
| | |
| Git creates commits based on a ''stage'' (also called ''index'' or ''cache'') that sits between the work tree and the repository.
| |
| After editing a file, say <code>Modules/readme.txt</code>, use [http://www.kernel.org/pub/software/scm/git/docs/git-status.html git status] to see the state of the stage and work tree:
| |
| | |
| $ git status
| |
| # On branch master
| |
| # Changed but not updated:
| |
| # (use "git add <file>..." to update what will be committed)
| |
| # (use "git checkout -- <file>..." to discard changes in working directory)
| |
| #
| |
| # modified: Modules/readme.txt
| |
| #
| |
| no changes added to commit (use "git add" and/or "git commit -a")
| |
| | |
| This tells you that no changes are staged for commit (i.e. the ''stage'' and ''HEAD'' commit have identical content),
| |
| and that the <code>Modules/readme.txt</code> file in the work tree has been modified from what is in the stage.
| |
| We stage the change using [http://www.kernel.org/pub/software/scm/git/docs/git-add.html git add]:
| |
| | |
| $ git add Modules/readme.txt
| |
| | |
| and check the status again:
| |
| | |
| $ git status
| |
| # On branch master
| |
| # Changes to be committed:
| |
| # (use "git reset HEAD <file>..." to unstage)
| |
| #
| |
| # modified: Modules/readme.txt
| |
| #
| |
| | |
| This tells you that changes have been staged for commit, and that the work tree is identical to the stage.
| |
| Now use [http://www.kernel.org/pub/software/scm/git/docs/git-commit.html git commit] to create a commit:
| |
| | |
| $ git commit
| |
| | |
| Git will bring up an editor interactively to ask for the commit message.
| |
| The editor will already have the output of <code>git status</code> in it as a reminder, but the comment lines will be removed from the message automatically.
| |
| A good convention is to use a short one-line summary (preferably 50 characters or less), then a blank line, then a detailed description:
| |
| | |
| Clarify documentation of module conventions
| |
|
| |
| The previous description of output variable XXX_YYY_ZZZ was not precise.
| |
| We clarify the wording and give an example.
| |
|
| |
| # Please enter the commit message for your changes. Lines starting
| |
| # with '#' will be ignored, and an empty message aborts the commit.
| |
| # On branch master
| |
| # Your branch is ahead of 'origin/master' by 1 commit.
| |
| #
| |
| # Changes to be committed:
| |
| # (use "git reset HEAD^1 <file>..." to unstage)
| |
| #
| |
| # modified: Modules/readme.txt
| |
| #
| |
| | |
| Upon exit it will create the commit (unless you leave the message blank to abort the commit).
| |
| After committing, check the status again:
| |
| | |
| $ git status
| |
| # On branch master
| |
| # Your branch is ahead of 'origin/master' by 1 commit.
| |
| #
| |
| nothing to commit (working directory clean)
| |
| | |
| This tells you that the (new) HEAD commit, stage, and work tree are all identical.
| |
| Furthermore it says you have one commit on your local <code>master</code> branch beyond what was last fetched from the upstream <code>origin/master</code> branch.
| |
| Use [http://www.kernel.org/pub/software/scm/git/docs/git-log.html git log] to see your commit:
| |
| | |
| $ git log origin/master..master
| |
| commit 0298957e33baab30cda0da625091260a0267a5a4
| |
| Author: Your Name <you@yourdomain.com>
| |
| Date: Thu Feb 4 14:37:53 2010 -0500
| |
|
| |
| Clarify documentation of module conventions
| |
|
| |
| The previous description of output variable XXX_YYY_ZZZ was not precise.
| |
| We clarify the wording and give an example.
| |
| | |
| The <code>origin/master..master</code> option says "show me commits reachable from <code>master</code> but not from <code>origin/master</code>".
| |
| In this case it is just the one commit.
| |
| | |
| One may also browse history interactively using [http://www.kernel.org/pub/software/scm/git/docs/gitk.html gitk].
| |
| | |
| ==Integration==
| |
| | |
| We use the branchy workflow documented [http://public.kitware.com/Wiki/Git/Workflow/Topic here].
| |
| Follow those instructions before publishing.
| |
| | |
| ==Publishing==
| |
| | |
| Authorized developers may publish work directly to <code>cmake.org/cmake.git</code> using Git's SSH protocol.
| |
| To request access, fill out the [https://www.kitware.com/Admin/SendPassword.cgi Kitware Password] form.
| |
| | |
| See the [[Git/Publish#Push_Access|push instructions]] for details.
| |
| | |
| For CMake, configure the push URL:
| |
| | |
| git config remote.origin.pushurl git@cmake.org:cmake.git
| |
| | |
| Once your push URL is configured and your key is installed for <code>git@cmake.org</code> then you can try pushing changes.
| |
| Continuing from the above commit example, you have one commit on your local <code>master</code> beyond what was last fetched from <code>origin</code>.
| |
| Use [http://www.kernel.org/pub/software/scm/git/docs/git-push.html git push] to send the changes back to <code>origin</code>:
| |
| | |
| $ git push
| |
| | |
| This shorthand push command works when your current local branch ''tracks'' a remote branch.
| |
| Git automatically configured the local <code>master</code> branch to track the remote branch <code>origin/master</code> upon cloning.
| |
| The configuration can be seen in <code>.git/config</code>:
| |
| | |
| [branch "master"]
| |
| remote = origin
| |
| merge = refs/heads/master
| |
| | |
| The configuration makes the above push command equivalent to the longhand form:
| |
| | |
| $ git push origin master:master
| |
| | |
| The <code>origin</code> option tells Git ''where'' to send history.
| |
| The <code>master:master</code> option tells Git ''what'' history to send.
| |
| The left part names a local branch to send, and the right part names the remote branch to update.
| |
| | |
| ===Update Hook===
| |
| | |
| The cmake.org repository has an <code>update</code> hook.
| |
| When someone tries to push changes to the repository it checks the commits as documented [[Git/Hooks#update|here]].
| |
| | |
| ==Topic Stage==
| |
| | |
| We provide a "[http://cmake.org/stage/cmake.git CMake Topic Stage]" repository to which developers may publish arbitrary topic branches and request automatic merges.
| |
| | |
| The topic stage URLs are
| |
| | |
| * <code>git://cmake.org/stage/cmake.git</code> (clone, fetch)
| |
| * <code>http://cmake.org/stage/cmake.git</code> (clone, fetch, gitweb)
| |
| * <code>git@cmake.org:stage/cmake.git</code> (push)
| |
| | |
| See our [http://public.kitware.com/Wiki/Git/Workflow/Stage Topic Stage Workflow] documentation for general instructions.
| |
| When accessing the CMake stage, one may optionally substitute
| |
| "<code>ssh git@cmake.org stage cmake ...</code>"
| |
| for
| |
| "<code>ssh git@public.kitware.com stage <repo> ...</code>"
| |
| in the ssh command-line interface.
| |
| | |
| {| border="0" | |
| !colspan=2|Stage Usage Summary
| |
| |- | | |- |
| |align="center"| | | |width=70%| |
| '''Initial Setup:'''
| | Main Tasks: |
| |
| |
| $ git remote add stage git://cmake.org/stage/cmake.git
| |
| $ git config remote.stage.pushurl git@cmake.org:stage/cmake.git
| |
| |- | | |- |
| |align="center"|
| |
| '''Fetch Staged Topics:'''
| |
| | | | | |
| $ git fetch stage --prune
| | :*<span style="font-size: 1.5em">[[Git/Download|Install Git]]</span> - Git 1.6.6 or greater is preferred |
| |- | | |- |
| |align="center"|
| |
| '''Create Local Topic:'''
| |
| | | | | |
| $ git checkout -b ''topic-name'' origin/master
| | :*<span style="font-size: 1.5em">[[CMake/Git/Download|Download CMake]] - Users start here</span> |
| $ edit files
| |
| $ git commit
| |
| |- | | |- |
| |align="center"|
| |
| '''Stage Current Topic:'''
| |
| | | | | |
| $ git push stage HEAD
| | :*<span style="font-size: 1.5em">[[CMake/Git/Develop|Develop CMake]] - Contributors start here</span> |
| |- | | |- |
| |align="center"|
| |
| '''Print Staged Topics:'''
| |
| | | | | |
| $ ssh git@cmake.org stage cmake print
| | Other Tasks: |
| |- | | |- |
| |align="center"|
| |
| '''Merge Staged Topic:'''
| |
| | | | | |
| $ ssh git@cmake.org stage cmake merge -b next ''topic-name''
| | :*<span style="font-size: 1.5em">[[CMake/Git/Dashboard|Test CMake]]</span> - CDash client setup |
| |- | | |- |
| |align="center"|
| |
| '''Abandon/Delete Staged Topic:'''
| |
| | | | | |
| $ git push stage :''topic-name''
| | :*<span style="font-size: 1.5em">[[Git/Resources|Learn Git]]</span> - Third-party documentation |
| |} | | |} |
|
| |
|
| After merging to '''next''' you are finished. Check the [http://www.cdash.org/CDash/index.php?project=CMake dashboard] the next day to see if your changes introduced any new problems. CMake core developers will review the topic during a weekly meeting and merge it to '''master''' or provide feedback if it is not ready. If you merge a topic to '''next''' that you do not consider ready for '''master''' please bring it up on the cmake-developers mailing list.
| | ''The remainder of this page provides reference information and links. It is not intended to provide instructions.'' |
| | |
| | ==Repositories== |
| | |
| | One may browse the repositories online using the Gitweb interface at http://cmake.org/gitweb. |
|
| |
|
| =Dashboard= | | {|border="1" cellspacing="0" cellpadding="3" |
| | !Repository |
| | !Purpose |
| | !Access |
| | !URL |
| | |- |
| | |rowspan=3|<code>cmake.git</code> |
| | |rowspan=3|CMake |
| | |clone (git) |
| | |<code>git://cmake.org/cmake.git</code> |
| | |- |
| | |clone (http) |
| | |<code>http://cmake.org/cmake.git</code> |
| | |- |
| | |push (ssh) |
| | |<code>git@cmake.org:cmake.git</code> |
| | |- |
| | |rowspan=3|<code>stage/cmake.git</code> |
| | |rowspan=3|CMake Topic Stage |
| | |clone (git) |
| | |<code>git://cmake.org/stage/cmake.git</code> |
| | |- |
| | |clone (http) |
| | |<code>http://cmake.org/stage/cmake.git</code> |
| | |- |
| | |push (ssh) |
| | |<code>git@cmake.org:stage/cmake.git</code> |
| | |} |
|
| |
|
| The [[#Branches| dashboard]] branch contains a dashboard client helper script.
| | ==Branches== |
| Use these commands to track it:
| |
|
| |
|
| $ mkdir -p ~/Dashboards/CMakeScripts
| | We use a topic-based workflow as documented [http://public.kitware.com/Wiki/Git/Workflow/Topic here] and thus define integration branches: |
| $ cd ~/Dashboards/CMakeScripts
| |
| $ git init
| |
| $ git remote add -t dashboard origin git://cmake.org/cmake.git
| |
| $ git pull origin
| |
|
| |
|
| The <code>cmake_common.cmake</code> script contains setup instructions in its top comments.
| | * '''maint''': Release maintenance; bug fixes only |
| | * '''master''': Release preparation; starting point for new features (default) |
| | * '''next''': Development; new features published here first |
|
| |
|
| =Resources=
| | We also provide additional branches: |
|
| |
|
| Additional information about Git may be obtained at sites listed [[Git/Resources|here]].
| | * '''nightly''': Follows '''next''', updated at 01:00 UTC |
| | * '''nightly-master''': Follows '''master''', updated at 01:00 UTC |
| | * '''release''': Latest release or release candidate. |
| | * '''dashboard''': Dashboard script ([[CMake/Git/Dashboard|setup]] a CDash client) |
| | * '''hooks''': Local commit hooks ([[Git/Hooks#Local|place]] in .git/hooks) |
