|
|
| (60 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 git version 1.7 or greater.
| |
| − | | |
| − | 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]].
| |
