Starting a Project Branch

So you’ve been hacking on erlide 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 project. Perhaps you’ve been accepted in the Google Summer of Code, or have a dire need to add support for a new fancy feature. Yep, you’re ready for a major erlide undertaking, and therefore your own branch.

If you were going to implement yaws support, you might want to create a branch called “dev_yaws”, like so:

git checkout -b dev_yaws master
git push origin dev_yaws

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 erlide repository on GitHub. 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 use the Git-standard message format. 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 dev_yaws
git pull 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 record 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, and then merge your changes into the master branch:

git commit -m 'Yaws support is ready to rock the house!'
git checkout master
git pull
git pull . dev_yaws
git push

This time, git pull will play back all of your commits in the dev_yaws branch as if you had written them directly into master in the first place (this is known as a “Fast-Forward” merge). This gives you the luxury to drop the dev_yaws branch, as it’s now redundant:

git branch -d dev_yaws
git branch -rd dev_yaws
git push

The first call to git branch deletes your working copy of the dev_yaws branch; the second call deletes the remote branch on GitHub. The call to git push makes it so.

And now you’re ready to hit the home page for your fork of the project and click the button to tell us to pull the new feature into the canonical repository.

So what are you waiting for? Get hacking!

This page is adapted from the pages written by David E. Wheeler for bricolage and is covered by a Creative Commons license. Thanks a lot!