Thoughts on the Proper Care and Feeding of Git Repos on GitHub

The nature of the problem

Last semester I and the other students working on Processing.js (Pjs) started using GitHub. We all made our own branch of the Pjs trunk repo and started hacking away. Over time we committed to our branches and some of our improvements went into trunk.

But our very success started to have some unintended consequences. Trunk advanced but our branches did not gain the improvements merged into trunk. This made our antiquated branches increasingly poor bases to produce patches for trunk. Needless to say, this inconvenience was not appreciated by anybody.

After a bit of experimentation I managed to find a way to keep my branch up to date without deleting it and starting fresh. Mickael Medel (aSydik), one of my classmates, has requested I spread the joy and blog about what I did. So here it is.

Fractional-reserve coding

In five easy steps most, if not all, problems, may be averted.

Step 1 – Pull from trunk to the branch on your local system

Before making any changes locally make sure you have the latest version of trunk. Pulling from trunk every time it changes isn't such a bad idea: it's much easier for Git to automatically merge code when the difference is small or simple. If the difference is too complex Git may cry "conflict!" and make you sort out the mess. Not good.

For us monkeys working on Pjs, I believe the pertinent pull command is:

git pull git://github.com/jeresig/processing-js.git master

Now, if you have more than one development system (as I do: desktop at home, and laptop) you may need to pull from your own repo instead of trunk. In that case the pertinent command is something like:

git pull git@github.com:yourusername/processing-js.git master

Step 2 – Hack on your local branch

So now have a totally updated version on your local system and the time has come for you to work your magic. Hack, surf, and make merry!

Step 3 – Commit on your local branch

After many hours of fruitful hacking you look out the window and the sun has been suspiciously replaced by the moon. It's time to call it a morning and push things back to your GitHub repo. But wait! Remember to commit the changes first, otherwise you'll have nothing to push.

I guess that Step 2 and 3 are just reminders, right?

Step 4 – Push your local commits to your online repo

Now comes the culmination of your efforts, fuelled by countless grams of caffeine and other tasty goodies: the big push. At this point you need to update your online repo to match the local repo. Not to hard, just plug in something that looks like this:

git push git+ssh://git@github.com/yourusername/processing-js.git

If all goes well the local commits will flood across cyberspace, and you shall know balance and harmony...

Step 5 – Back to Step 1

… for a little while. When you're ready to go at it again, collect your $200 and sally back to Step 1.

Opposites attract, but sometimes we wish they wouldn't

The above works very well if your branch is kept up to date. But if you're sitting on some really old revision chances are Git will be unable to do the merge in Step 1. It'll cry "conflict!" and you'll have to sort it out. By this I mean you'll need to do the merge manually (yes, lots of copying and pasting and what not.)

If the situation is really bad you may simply want to kill and remake your branch from scratch, keeping in mind to regularly update the resuscitated branch this time round.

If you slog through the manual merge, then commit changes to finish the merge. Committing will also tell Git the conflict has been resolved and you'll be back in business. At least, that's what I think happened when I resolved my first (and so far only) conflict.

Only now, at the end, do you understand.

I hope that was helpful for those in need.

I apologize to Mickael for the tardy post. He asked for this last Thursday and it took me a while to cobble this together. You see, I use an unholy combination of the command line and the EGit plugin for Eclipse to interface with GitHub so I wasn't quite sure what the exact commands were. I tested them with my latest commit to GitHub so I hope they work for everybody else.

Yes, I use Eclipse to hack Processing.js, but only because EGit appeals to my laziness. Otherwise I'd do what sane people do and use a "regular" text editor.