Git ‘er done


It would be great if Github would be clearer about this, but be aware that if you are contributing to someone else’s project by way of forking their repository into your account, you’re going to want to keep your pull request’s clean. First of all, you more than likely want the master branch of your fork to be a mirror of the main project. That is, you will want your fork to have the exact same commit history as the main one you’re following. From there, you would create branches off of your master, topic branches if you will, that contain the changes you propose. You would then make pull requests based off these topic branches so that your initial request consists of a single commit that may change one or more files.

If you were like me, you were probably using the following to update your fork’s master branch:

    git pull upstream master

Which fetches the commit history from the upstream repo, which is the main one you wish to track, and merges it into your own. Doing so causes your local repo to make a new commit that is based on whatever commit history came from the upstream. If you always did this to update your local repo and then push it to your fork on Github, you’d always have new commits that log these updates. This ultimately results in a not very clean commit history, which will be evident when you make a pull request that changes a single file and ends up dragging along 10+ commits with it.

To update your fork to mirror that main repo you wish to track, you want to fetch changes from the upstream and then rebase them onto your master. First, make sure you are on your local repo’s master branch, and then enter the following:

    git pull --rebase upstream master

This will update your local repo’s master branch in a clean fashion and truly mirror the main repository’s commit history with yours. Go ahead and do this if your commit history is cluttered and you want to get back on track, then push the changes to your fork on Github, which should be named origin, of course. If Git refuses to push your changes due to altered commit history, be sure to review the state of your local repo with git log or a more detailed GUI and then do a force push:

    git push -f origin master

Now your local repo and fork on Github will look just like the master branch in the main repo you’re tracking. You can propose changes by creating branches off your master and Github’s Pull & Compare feature will confirm your pull requests are clean.

I thank the great people of StackOverflow for letting me in on this practice. Git takes some time to get used to, but the rewards are plentiful. I’m nowhere near an expert, but I’m gittin’ the hang of it. Some of the most useful resources I’ve stumbled across are GitHub’s Help page, the online book Pro Git, and this comprehensive markdown syntax guide.

What say you?