VTK/Git/GitHub

This page documents how to use GitHub along with the VTK development workflow. See our table of contents for more information.

This page was copied from the GitHub section of the old front page as it appeared prior to 2012-02-01. If you modify it to account for the new workflow please remove this message.

The VTK repository is mirrored on github. Experimental branches that are not ready for staging can be published on github for review.

The first step in creating a github branch is to create an account on github and make a fork of http://github.com/Kitware/VTK. Since this fork will be a mirror of the VTK master, there is no need to clone it on your local machine. Instead, you will just want to set github as an alternative remote in your existing local copy of the VTK git repository.

To set github as an alternative remote, use the following commands:

Github Usage Summary
Remote Setup:	$ git remote add github git@github.com:yourname/VTK.git $ git config remote.github.pushurl git@github.com:yourname/VTK.git
Update the Remote:	# update from Kitware's master and push to github $ git pull $ git push github HEAD
Push Branch to Github:	$ git checkout -b some-branch github/master # edit files and commit changes $ git push github HEAD

The "update remote" step above should be done regularly on your master, in order to keep your github fork up-to-date with the VTK master. Do not use github's graphical interface for merging commits, it creates new commits by rebasing the commits you select against your VTK fork. These rebased commits will be very difficult to merge back into VTK master.

The checkout command in the third step will automatically set github as the default remote for the new branch, but you still must specify "github HEAD" when you push or else you will push to the github master branch, instead of pushing to a new github branch. Also, since it bases the branch on your github fork, you should perform step 2 before creating the branch to make sure that your fork is up-to-date. This is just a suggestion, as it is always possible to rebase or merge at a later time.

The default remotes for each of your branches are controlled by entries such as this in your .git/config file:

[branch "my-branch-name"]
	remote = github
	merge = refs/heads/my-branch-name

You can edit this file to make github the default remote and to set the remote branch name for your existing branches. Or you can always use "git push github HEAD" to push each branch to github, without changing the defaults.