|
|
| (61 intermediate revisions by 10 users not shown) |
| Line 1: |
Line 1: |
| __TOC__
| | The instructions previously available on this page have been superseded. See [https://gitlab.kitware.com/vtk/vtk/blob/master/Documentation/dev/git/README.md here]. |
| | |
| VTK version tracking and development is hosted by [http://git-scm.com Git].
| |
| | |
| =Official Repository=
| |
| | |
| One may browse the repository online using the [http://git.wiki.kernel.org/index.php/Gitweb Gitweb] interface at http://vtk.org/gitweb.
| |
| | |
| ==Cloning==
| |
| | |
| These instructions assume a command prompt is available with <code>git</code> in the path.
| |
| See our Git [[Git/Download|download instructions]] for help installing Git.
| |
| | |
| 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://vtk.org/VTK.git VTK
| |
| | |
| or through the (less efficient) <code>http</code> protocol:
| |
| | |
| $ git clone http://vtk.org/VTK.git VTK
| |
| | |
| All further commands work inside the local copy of the repository created by the clone:
| |
| | |
| $ cd VTK
| |
| | |
| For VTKData the URLs are
| |
| | |
| git://vtk.org/VTKData.git
| |
| http://vtk.org/VTKData.git
| |
| | |
| ==Branches==
| |
| | |
| At the time of this writing the repository has the following branches:
| |
| | |
| * '''master''': Development (default)
| |
| * '''release''': Release maintenance
| |
| * '''nightly-master''': Follows '''master''', updated at 01:00 UTC
| |
| * '''hooks''': Local commit hooks ([[Git/Hooks#Local|place]] in .git/hooks)
| |
| | |
| Release branches converted from CVS have been artificially merged into master.
| |
| Actual releases have tags named by the release version number.
| |
| | |
| =Development=
| |
| | |
| We provide here a brief introduction to '''VTK''' development with Git.
| |
| See the [[Git/Resources|Resources]] page for further information such as Git tutorials.
| |
| | |
| ==Introduction==
| |
| | |
| We require all commits in VTK to record valid author/committer name and email information.
| |
| 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"
| |
| | |
| Note that "Your Name" is your ''real name'' (e.g. "John Doe", not "jdoe").
| |
| While you're at it, 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.
| |
| | |
| ==Hooks==
| |
| | |
| The '''hooks''' branch provides local commit hooks to be placed in <code>.git/hooks</code>.
| |
| It is shared by many <code>public.kitware.com</code> repositories.
| |
| | |
| See the general [[Git/Hooks|hooks]] information page to set up your local hooks. | |
| | |
| ==Workflow==
| |
| | |
| We've chosen to approximate our previous CVS-based development workflow after the initial move to Git, at least while things get settled.
| |
| The basic rule is to rebase your work on origin/master before pushing:
| |
| | |
| git fetch origin
| |
| git rebase origin/master
| |
| | |
| or
| |
| | |
| git pull --rebase
| |
| | |
| The server will refuse your push if it contains any merges.
| |
| Later we will move to a full [http://public.kitware.com/Wiki/Git/Workflow/Topic branchy workflow] based on topic branches.
| |
| | |
| We already provide support for topic branches and merges through the VTK Topic Stage described in the next section.
| |
| | |
| ==Topic Stage==
| |
| | |
| We provide a "[http://vtk.org/stage/VTK.git VTK Topic Stage]" repository to which developers may publish arbitrary topic branches and request automatic merges. To follow this workflow, you should have at least git version 1.7.
| |
| | |
| The topic stage URLs are
| |
| | |
| * <code>git://vtk.org/stage/VTK.git</code> (clone, fetch)
| |
| * <code>http://vtk.org/stage/VTK.git</code> (clone, fetch, gitweb)
| |
| * <code>git@vtk.org:stage/VTK.git</code> (push)
| |
| | |
| See our [http://public.kitware.com/Wiki/Git/Workflow/Stage Topic Stage Workflow] documentation for general instructions.
| |
| ''(Currently VTK does not have a '''next''' branch. Just skip that part of the instructions and merge directly to master.)''
| |
| When accessing the VTK stage, one may optionally substitute
| |
| "<code>ssh git@vtk.org stage VTK ...</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"|
| |
| '''Initial Setup:'''
| |
| |
| |
| $ git remote add stage git://vtk.org/stage/VTK.git
| |
| $ git config remote.stage.pushurl git@vtk.org:stage/VTK.git
| |
| |-
| |
| |align="center"|
| |
| '''Fetch Staged Topics:'''
| |
| |
| |
| $ git fetch stage --prune
| |
| |-
| |
| |align="center"|
| |
| '''Create Local Topic:'''
| |
| |
| |
| $ git checkout -b ''topic-name'' origin/master
| |
| $ edit files
| |
| $ git commit
| |
| |-
| |
| |align="center"|
| |
| '''Stage Current Topic:'''
| |
| |
| |
| $ git push stage HEAD
| |
| |-
| |
| |align="center"|
| |
| '''Print Staged Topics:'''
| |
| |
| |
| $ ssh git@vtk.org stage VTK print
| |
| |-
| |
| |align="center"|
| |
| '''Merge Staged Topic:'''
| |
| |
| |
| $ ssh git@vtk.org stage VTK merge ''topic-name''
| |
| |}
| |
| | |
| Note that the stage implementation is not VTK-specific and is used for other projects too.
| |
| If the merge attempt conflicts it may print instructions for performing the merge manually.
| |
| '''Ignore''' these instructions; you will not be able to push the merge commit directly.
| |
| Instead, identify the commit that conflicts with yours, merge it into your topic locally, push the topic to the stage again, and then repeat the merge request.
| |
| | |
| =Publishing=
| |
| | |
| ==Pushing==
| |
| | |
| Authorized developers may publish work directly to <code>vtk.org/VTK.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 VTK, configure the push URL:
| |
| | |
| git config remote.origin.pushurl git@vtk.org:VTK.git
| |
| | |
| For VTKData, configure the push URL:
| |
| | |
| git config remote.origin.pushurl git@vtk.org:VTKData.git
| |
| | |
| ===Update Hook===
| |
| | |
| The vtk.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]].
| |
| | |
| ==Patches==
| |
| | |
| Contributions of bug fixes and features are commonly produced by the community. Patches are a convenient method for managing such contributions.
| |
| | |
| One may send patches after subscribing to our mailing list:
| |
| | |
| * [http://www.vtk.org/mailman/listinfo/vtk-developers VTK Developers Mailing List]
| |
| | |
| See our [[Git/Publish#Patches|patch instructions]] for details.
| |
| | |
| = Troubleshooting =
| |
| == fatal: The remote end hung up unexpectedly ==
| |
| * If <tt>git push</tt> fails with "fatal: The remote end hung up unexpectedly", you probably forgot to set the push url with "git config" see [[#Pushing]].
| |
| | |
| == Restoring files locally ==
| |
| Q: "I cloned the VTK repository. Now I "rm -rf Hybrid". How do I get it back?"<br>
| |
| A: git checkout Hybrid<br>
| |
| Q: "I modified a file locally. I want to revert it."<br>
| |
| A: git checkout myfile.cxx
| |
| | |
| =Resources=
| |
| | |
| Additional information about Git may be obtained at sites listed [[Git/Resources|here]].
| |
