Starting a project branch

So you've been hacking on fpGUI for a while, fixed a few bugs in the master branch and in a maintenance branch, and now you're ready to take on a big feature in the fpGUI project. Yep, you're ready for a major fpGUI undertaking, and therefore your own branch.

I'm assuming that you're using a recent version of Git, v1.7 or later. Now lets say your are working on a super cool reporting engine for fpGUI. This is how you would start.

git checkout -b reporting master
git push origin -u reporting

The call to git checkout -b creates the new branch from the master branch. The call to git push, meanwhile, pushes the new branch to your forked copy of the fpGUI repository on GitHub. The -u option sets the local branch to track the remote branch.

Now you're set to work on your new branch like you would any other branch. You can do whatever you like in this branch, though we do recommend that you commit early and often and try to use a good commit messages standard to describe each commit. Push to your fork regularly, too.

Periodically, you'll want to pull changes down from the project repository upstream and merge them into your branch. Doing so is a cinch with Git. First, make sure that your master branch is up-to-date:

git checkout master
git pull
git pull upstream master
git push

Now switch back to your project branch and merge in the changes:

git checkout reporting
git merge master

The beautiful thing about Git merges is that they are self-tracking, so you don't have to remember where you left off the last time you merged, as you would with CVS or Subversion. Furthermore, if there are no conflicts, Git will simply replay all of the merges into your branch. This means that you get the complete commit history from master. If there are conflicts, Git will let you know. Just go and resolve them by modifying the files containing the conflicts and then git commit when you're done.

Once you have finished developing your new feature (including tests, right?), make sure that you get it all committed and up-to-date, merged with the latest from the master branch, and pushed to your fork on GitHub.

And now you're ready to hit the home page for your fork of the project and click the "Pull Request" button to tell us to pull the new feature into the canonical repository. Or simply post a message to the fpGUI newsgroup mentioning the repository and branch that must be pulled from. Once your branch has been accepted and merged into the upstream repository, you can pull from the merged master branch from upstream and drop your local and remote branches.

git checkout master
git pull upstream master
git push
git branch -D reporting
git push origin --delete reporting

So what are you waiting for? Get hacking! ;-)