VTK/Working With Git

VTK will be moving to Git, likely hosted on our own instance of Gitorious. Git is quite different to traditional, centralized version control systems. It is a DVCS (Distrubuted Version Control System). It was coded by Linus Torvalds and others primarily to handle the Linux kernel's very distributed development model.

There are lots of guides around that help you to work with Git. A good quick start guide is everyday Git. In a normal workflow we recommend that you sign up for a Kitware Gitorious account, go to the VTK repository page and clone the repository, you will then have your own copy of the Git repository. You can keep this up to date using the web interface or Git on the command line, and can make merge requests when your changes are ready for integration.

If granted push privileges you will also be able to merge your changes directly into VTK master.

Configuring Git

The first thing you will want to do is tell Git who you are. This will be used in commit messages and attributions.

git config --global user.name "Your Name"
git config --global user.email "you@yourdomain.com"

If you are like me you may also want to add some color to the Git output.

git config --global color.ui auto

One or Two Patches

If you just have one or two patches you would like to submit you probably just want to clone the main VTK repository.

git clone git://gitorious.kitware.com/VTK/vtk.git

Make any changes you like, commit them to your local repository and then use git format-patch to make a patch. When the patch is applied it goes into Git just like any other commit, and you get full credit. For this reason you should ensure you set up your name and email correctly before committing anything/emailing it.

Existing VTK Contributors

This Git stuff all sounds great, but how do I just keep doing what I am doing? This section is intended to mirror as closely as possible the workflows employed by existing developers who are currently using CVS. It is not an optimal workflow, you may want to consider the points made in the Git CVS crash course.

One thing that you must remember is that all commits are local until you push them. When they are local you can do lots of things to them such as rewrite history, rebase your changes (effectively what CVS does every time you run 'cvs up'), etc, that you should not do to changes that were pushed.

Checkout VTK

You will normally work on 'master', which is the equivalent to 'trunk' or 'HEAD' in CVS terms. You should ensure that you have at least set up your name and email address in Git, as described above. To checkout a copy of the VTK repository,

git clone git://gitorious.kitware.com/VTK/vtk.git

Updating: 'cvs up' equivalent

In order to pull the latest changes into your local checkout issue the following command,

git pull

If you have local, uncommitted changes you can use git stash to stash your changes away, and git stash apply to bring them back.

Committing Changes

In order to commit your changes there are two steps, due to the distributed nature of Git.

git commit -a

Effectively does the same thing that cvs commit did, and similar commands such as git add path/to/new/file will add the new file to the repository. All of these changes are local until you perform the second step.

git push

This command pushes all of the locally committed changes in this branch to the server, so that others can see your change. This has the distinct advantage that you can commit changes locally all day and night, pushing these changes in the morning so that they can receive maximum testing on the dashboards.

Viewing Logs

Viewing the logs is very similar to CVS,

git log

Viewing Changes

Viewing the changes between your code and the last locally updated state of the repository is easy. Be careful, as this command does not check with any server, as CVS did. Only push and pull really involve the network.

git diff

Views all changes that have not been committed (locally or on the server).

Contributing to VTK

If you would like to get more involved with VTK, and begin making contributions to our code on a longer term basis, you should take the following steps:

• Create an account on Kitware Gitorious.
• Go to the VTK project page and click on the clone button.
• Clone your user clone repository to your local machine.
• It is often convenient to make a topic branch for individual features or fixes, git checkout -b newfeaturebranch master.
• Make any changes you want to make, commit them and do a git push.
• Make a merge request to VTK, this will be reviewed by a VTK developer.

While getting used to Git there are several guides such as the Git cheat sheet, forking and submitting modifications, and keeping a git fork in sync with upstream. You can also ask questions on our mailing list.

Managing Multiple Remotes, Integrating

In order to integrate the changes of other developers we can either use the merge request queue, or manage things using command line Git. The command line is often quicker once you get the hang of it, but it can take a little getting used to. Once you have your clone of the repository you can add multiple remotes and fetch their history, view changes relative to your master and merge in these changes.

git remote add jeff git://gitorious.kitware.com/~jeff/vtk.git
git remote update

Once a developer makes some commits and requests that they are pulled into the repository you need to update your copy of their repository, merge the changes and push to the master repository. Ideally they will have a topic branch that they pushed, with only the changes they would like to be merged in that topic branch.

git checkout master
git fetch jeff
git merge jeff/fancy-new-infoviz-view
git log -p
git push

You can also use git cherry-pick to pick off individual commits to apply. Never rebase anything that has been pushed as this will break history for other poeple's checkouts. When using private feature/topic branches rebasing is preferable, but not in public branches. This also applies to commits which you later decide are not appropriate - once they have been pushed they must be reverted rather than edited/removed.

Using multiple branches

In Git it is very easy to have several branches. Usually, you keep one branch per feature, so called "topic branches".

Because git tracks merges, output from "git log master..topic_branch" gives all you need to know about topic_branch and how it differs from master. The command lists changes that are still not merged to master on the topic_branch. If the list is empty, topic_branch contains no changes that have not been merged into master. At this point you can safely delete the topic branch as its history has already been merged into master.

For more details refer to one of the linked tutorials or online books.

Further Information

There is a Git Community Book and Pro Git, both of which provide much more detail than could be provided here. If you would like to learn more about using Git both of these free, online resources are highly recommended. Most developers should be able to get up and running with the details provided on this page.