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.org/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

Optionally, call your local copy tubetk by adding tubetk onto the end of the above line.

Then, setup a reference to the TubeTK central repository:

cd <yourName>-tubetk    (or cd tubetk, if you did the optional step above)
git remote add upstream git@gitorious.org:tubetk/tubetk.git
git fetch upstream

Setting up your git environment

We have provided a linux shell script for setting up your GIT environment for software development. It is provided in

 tubetk/Utilities/SetupForDevelopment.sh

Below are instructions for setting up your environment manually.

If you want a refresher on GIT usage, see GIT Tips and Tricks

Setup Global GIT Environment

As mentioned above, we have provided a script that will walk you through setting up your GIT environment, below is only necessary if you are setting up your environment manually.

If you are manually configuring your environment, please substitute your information as appropriate into the following commands:

git config --global user.name 'Your Name'
git config --global user.email 'you@yourdomain.com'
git config --global color.ui auto
git config --global merge.tool meld

For more details and other global variable options, see Manually configuring your global GIT environment

Setup Hooks

As mentioned above, we have provided a script that will walk you through setting up your GIT environment, below is only necessary if you are setting up your environment manually.

Hooks check your code prior to allowing it to be committed to the main repository. Details on the checks performed are available at TubeTK 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. This is a pain and is prone to errors, so we recommend installing hooks locally to make sure your code is compliant even on local commits.

Enabling TubeTK's local hooks will prevent problems when pushing your contributions to the public TubeTK repository. This is so important to the smooth functioning of git that we REQUIRE that you enable TubeTK's hooks in all clones. TubeTK uses the same hooks as VTK.

Git looks for hooks in the .git/hooks directory within the work tree of a local repository.

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.

General details on hooks in git are available here.

Optionally, you may now also want to ignore temp files created by your editor

 cd ~/src/tubetk/.git/info
 vi exclude
 # now uncomment the "*~" line and, if appropriate, add a "*.swp" line.  Then save.

Adding a feature to TubeTK

• 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>

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:

Optional: consider rebasing your branch to upstream master. This is optional, but will allow you to address conflicts, verify tests, and maintain a clearer git history. See "The case for GIT rebase" and "GIT Rebase Documentation" for more information.

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:

• The --no-ff option generates a merge commit even if the merge was resolved as a fast-forward merge: using this option makes the history easier to understand

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")