TubeTK/Development/GITBranchingUsage

From KitwarePublic
Jump to navigationJump to search

Git commands for a branchy workflow

  • All developments should use the 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 [www.gitorious.com | Gitorious ]
  • Add your computer's public SSH key (log into your gitorious account, go to your "Dashboard" page and select "Manage SSH keys")
  • Clone the TubeTK central repository:

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

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.

Get changes from others

From the central repository

To get changes that have been committed to the location you originally cloned from:

git stash            # Push your uncommitted local changes to a stack.  Be careful, they are not saved anywhere else.
git pull upstream
git stash pop        # To re-apply the changes on the stack to the local repository

From other repositories

Pull changes made by another developer in his/her public repository, but not yet committed to the central repository:

git pull git://<some-other-repo>.git master

'git remote' can be used to manage short names for repositories that you frequently pull from.

From patches

Apply a patch from another developer, preserving the other developer's identity as the patch author:

git am --signoff patch.mbox

Prepare commits to share with fellow developers

With git, it's possible to record every edit and false start as a separate commit. This is very convenient as a way to create checkpoints during development, but often you don't want to share these false starts with others.

Git provides two main ways to do this, both of which can be done freely before you share the change:

  • 'git commit --amend' lets you make additional changes a part of the last thing you committed, optionally modifying the commit message as well. Use this if you realized right away that you left something out of the commit, or if you typo'd the commit.
  • 'git rebase --interactive origin' lets you go back through each change made since 'origin', possibly editing it or combining ('squashing') it with another change. In the most extreme case, you can 'squash' it into a single commit, if there's no value to other developers in seeing the individual steps.
    • For example, to squash the most recent four commits into one commit:
git rebase --interactive HEAD~4
change all lines except the first one to “squash” instead of “pick”, and save (note list of commits is backwards, from oldest at top to newest at bottom)
edit the commit message, and save
    • At any time, to abort the rebase:
git rebase --abort

Send patches through e-mail or the web

When you think your changes are ready to be used by others, you can share it in the form of a patch. Make a series of patches for each commit in your local branch but not in 'origin':

git format-patch -M origin

This creates a number of files with names like

0001-my-well-intentioned-change.patch

These patch files are suitable for putting on a webserver or for sending as e-mail with your favorite mail client or git-send-email (some configuration required).

To submit a patch, email it to one of the TubeTK Developers.

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