|
|
| (63 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| __TOC__
| | The instructions previously available on this page have been superseded. See [https://gitlab.kitware.com/cmake/cmake/blob/master/Help/dev/README.rst here]. |
| | |
| CMake version tracking and development is moving to [http://git-scm.com Git].
| |
| | |
| =Experimental Repository=
| |
| | |
| We have published an ''experimental'' repository on <code>cmake.org</code>.
| |
| '''WE REQUEST THAT NO ONE PUBLISH A CLONE OF THIS REPOSITORY AT AN ONLINE HOSTING SITE.''' This may or may not be the final version of history after conversion from CVS. It may be removed or rewritten at any time. We prefer to '''not have multiple incompatible histories''' out there. The final conversion will be available soon, at which point we may all begin sharing changes!
| |
| | |
| ''At the time of this writing it has only the development mainline and no branches or tags.''
| |
| These will be converted and added later without hindering the main move.
| |
| | |
| 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-tmp.git CMake
| |
| | |
| or through the (less efficient) <code>http</code> protocol:
| |
| | |
| $ git clone http://cmake.org/cmake-tmp.git CMake
| |
| | |
| The repository is also available by anonymous cvs pserver, served by [http://www.kernel.org/pub/software/scm/git/docs/git-cvsserver.html git cvsserver].
| |
| The server maps git branches to cvs modules, so one must ask cvs to get the module "master":
| |
| | |
| $ cvs -d :pserver:anonymous@cmake.org:/cmake-tmp.git co -d CMake master
| |
| | |
| One may browse the repository online using the [http://git.wiki.kernel.org/index.php/Gitweb Gitweb] interface at http://cmake.org/gitweb.
| |
| | |
| =Development=
| |
| | |
| We provide here a brief introduction to development with Git.
| |
| See the [[#Resources|Resources]] below for further information.
| |
| | |
| 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.
| |
| 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 that your local <code>master</code> has a commit on top of what was last fetched from <code>origin</code>.
| |
| | |
| ==Publishing==
| |
| | |
| The experimental repository is unofficial and changes published in it are not considered part of the project.
| |
| However, developers may experiment with publishing work as follows.
| |
| | |
| Git automatically configures a new clone to refer to its origin through a [http://www.kernel.org/pub/software/scm/git/docs/git-remote.html remote] called <code>origin</code>.
| |
| Initially one may [http://www.kernel.org/pub/software/scm/git/docs/git-fetch.html fetch] or [http://www.kernel.org/pub/software/scm/git/docs/git-pull.html pull] changes from <code>origin</code>,
| |
| but may not [http://www.kernel.org/pub/software/scm/git/docs/git-push.html push] changes to it.
| |
| | |
| In order to publish new commits in the <code>cmake.org</code> repository, developers must configure a ''push URL'' for the <code>origin</code>.
| |
| Use [http://www.kernel.org/pub/software/scm/git/docs/git-config.html git config] to specify an ssh-protocol URL:
| |
| | |
| git config remote.origin.pushurl git@cmake.org:cmake-tmp.git
| |
| | |
| All publishers share the <code>git@cmake.org</code> account but each uses a unique ssh key for authentication.
| |
| To request access, fill out the [https://www.kitware.com/Admin/SendPassword.cgi Kitware Password] form.
| |
| Include your ssh public key and a reference to someone our administrators may contact to verify your privileges.
| |
| | |
| Note that ''we may not grant all contributors push access'' to the <code>cmake.org</code> repository.
| |
| The distributed nature of Git allows contributors to retain authorship credit even if they do not publish changes directly.
| |
| '''After the final conversion to Git''' is finished we will consider pull requests from online Git hosting sites.
| |
| | |
| =Resources=
| |
| | |
| Additional information about Git may be obtained at these sites:
| |
| | |
| * [http://git-scm.com Git Homepage]
| |
| * [http://book.git-scm.com/ Git Community Book]
| |
| * [http://www.kernel.org/pub/software/scm/git/docs/everyday.html Everyday Git]
| |
| * [http://github.com/guides/git-cheat-sheet Git Cheat-Sheet]
| |
| * [http://progit.org/book/ Pro Git]
| |
