TubeTK/Development/GITBranchingUsage

Git commands for a branchy workflow

• TubeTK policy is to follow a branchy workflow.
• All developments should use the branch workflow to maintain an organized git history in TubeTK
• Key concepts:
  • Each feature should be developed in its own separate branch on the author's public repository (i.e. the author's clone of TubeTK on Gitorious)
  • git often uses "topic" as a placeholder for a branch name, because everything in a branch should be on one "topic"--a topic might be to add feature X, refactor subsystem Y, only fix bugs from version Z, and so on.
  • Once the feature has been programmed and tested, its branch should be merged into TubeTK's master branch ('master' is the git equivalent of cvs 'TRUNK')
  • After the feature has been merged, its branch should be deleted

TubeTK's central repository is hosted on [www.gitorious.com | Gitorious ]. You can host a public repository to which you "push" and from which others can "pull". If you don't have a server of your own to do this, services like github and gitorious are free for open source projects. After you push to your own public repository, other developers can browse your changes or "pull" them.

Setting up your personal TubeTK public repository

• Create an account at Gitorious
• Add your computer's public SSH key (log into your gitorious account, go to your "Dashboard" page and select "Manage SSH keys")
  • Gitorious has an FAQ on creating Windows ssh keys
• Clone the TubeTK central repository to create your personal TubeTK public repository:
  • Go to http://www.gitorious.com/tubetk and click the "Clone repository" button
  • In the examples below, <yourName> is the name of your Gitorious account

Setting up your local and remote repositories

Your local repository is git's repository local on your machine.

Your remote repositories should be as follows:

• origin: your public repository
• upstream: the TubeTK central repository

First, setup your local repository by cloning your public repository. This will create a folder called <yourName>-tubetk in a directory called 'Projects':

cd Projects
git clone git@gitorious.org:~<yourName>/tubetk/<yourName>-tubetk.git

Then, setup a reference to the TubeTK central repository:

git remote add upstream git@gitorious.org:tubetk/tubetk.git

Setup Hooks

The git commit command creates local commits. A separate git push step is needed to publish commits to a public.kitware.com repository. The public.kitware.com server enforces some rules on the commits it accepts and will reject non-conforming commits. In order to push rejected commits, one must edit history locally to repair them before publishing.

Since it is possible to create many commits locally and push them all at once, we provide local Git hooks to help developers keep their individual commits clean. Enabling these hooks will prevent problems when pushing your contributions to the public TubeTK repository. Git provides no way to enable such hooks by default, giving developers maximum control over their local repositories. We recommend enabling our hooks manually in all clones.

Git looks for hooks in the .git/hooks directory within the work tree of a local repository. Create a new local repository in this directory to manage the hooks and fetch VTK's hooks into that directory.

$ cd ~/src/tubetk/.git/hooks
$ git init
$ git pull git://public.kitware.com/VTK.git hooks
$ cd ../..

where ~/src/tubetk is your TubeTK source directory.

See Git help on githooks for more details.

Understanding TubeTK's Hooks

For details on the VTK hooks used with TubeTK (and how to make your commit's comply with their requirements), visit TubeTK/VTK Hooks

Remote repository setup

• origin: keeps a master branch that is only a pointer to the TubeTK master branch, + any of your topic branches
• upstream: has a master branch

Adding a feature

• A feature may be new functionality, a new test, a bug fix, performance enhancements, added documentation, style fixes, etc.
• Each feature should have its own branch
• Do all of your work in a topic branch, not in master. Do not git add/git update in the master branch.

• In the workflow below, <topic> refers to the name of your branch.

For new features, use the git 'upstream/master' branch as the starting point:

git checkout master
git fetch upstream
git merge upstream/master
git checkout -b <topic>
git push origin <topic>:refs/heads/<topic>

All commits for that feature should be committed to the topic branch:

git checkout <topic>
 code, code, code 
git add -u
git commit
 code, code, code 
git add -u
git commit
git push origin <topic>
 code, code, code 
git add -u
git commit
 code, code, code 
git add -u
git commit
git push origin <topic>

After the feature is completed and tested, merge its topic branch to TubeTK's master branch:

First, make sure that your local master branch is up to date, by fetching and merging all of the changes that have recently occurred on the TubeTK master branch:

git checkout master
git fetch upstream
git merge upstream/master

Next, merge your topic branch to your local master branch:

git merge <topic> --no-ff
 you may have to fix merge conflicts 
 run tests again, to ensure that the merge did not introduce problems 

Now, publish your changes to your public repository:

git push origin master

If you're been approved to directly push your changes to the central repository, then after some initial setup of ssh keys its a very simple procedure:

git push upstream master

(If another developer pushed between your pull and your push, you will have to pull and then push again. This isn't expected to happen very frequently, but it will happen more frequently than with cvs since it's required when any file changed, not just when a specific file being committed changed. It is also best to use "git pull --rebase" instead of "git fetch upstream"/"git merge upstream/master" in this case, this will cause the changes from the central repository to be positioned before your own changes, thus skipping a merge.)

Delete your topic branch both locally and on your public repository.

git checkout master
git branch -d <topic>
git push origin :<topic>

If you want to add more features, start over with a new topic branch.

Use multiple commits to organize changes

When appropriate, organize your changes into a series of commits where each commit is a logical step towards your ultimate goal. For example, first factor out some complex code into a new function. Then, in a second commit, fix an underlying bug. Then, in the third commit, add a new feature which is made easier by the refactoring and which would not have worked without fixing that bug. This is helpful to reviewers, because it is easier to see that the "factor out code into new function" step was right when there aren't other edits mixed in; it's easier to see that the bug is fixed when the change that fixes it is separate from the new feature; and so on.

Policy

Just because a thing can be done with git doesn't mean it should be done.

• Please don't revise history after it's been made publicly available (i.e. don't revise history after a "git push")