Git and Github: keeping a feature branch updated with upstream?

Git and github, you gotta love them for managing and contributing to (FLOSS) projects.

Contributing to a Github hosted project becomes very easy. Fork the project to your personal Github account, clone your fork locally, create a feature branch, make some patch, commit, push back to your personal Github account, and issue a pull request from your feature branch to the upstream (master) branch.

git clone -o svg
cd ansible
git remote add upstream git://
git checkout -b user-non-unique
vi library/user
git add library user
git commit -m "Add nonunique option to user module, translating to the -o/--non-unique option to useradd and usermod."
git push --set-upstream svg user-non-unique
[go to github and issue the pull request]

Now, imagine upstream (1) doesn’t approve your commit and asks for a further tweak and (2) you need to pull in newer changes (upstream changes that were committed after you created your feature branch.)

How do we keep this feature branch up to date? Merging the newest upstream commits is easy, but you want to avoid creating a merge commit, as that won’t be appreciated when pushed to upstream: you are then effectively re-committing upstream changes, and those upstream commits will get a new hash (as they get a new parent). This is especially important, as those merged commits would be reflected in your Github pull request when you push those updates to your personal github feature branch (even if you do that after you issued the pull request.)

That’s why we need to rebase instead of merging:

git co devel #devel is ansible's HEAD aka "master" branch
git pull --rebase upstream devel
git co user-non-unique
git rebase devel

Both the rebase option and rebase command to git will keep your tree clean, and avoid having merge commits.
But keep in mind that those areyour first commits (with whom you issued your first pull request) that are being rebased, and which now have a new commit hash, which is different from the original hashes that are still in your remote github repo branch.

Now, pushing those updates out to your personal Github feature branch will fail here, as both branches differ: the local branch tree and the remote branch tree are “out of sync”, because of those different commit hashes. Git will tell you to first git pull --rebase, then push again, but this won’t be a simple fast-forward push, as your history got rewritten. Don’t do that!

The problem here is that you would again fetch your first changed commits as they were originally, and those will get merged on top of your local branch. Because of the out of sync state, this pull does not apply cleanly. You’ll get a b0rken history where your commits appear two times. When you would push all of this to your github feature branch, those changes will get reflected on the original pull request, which will get very, very ugly.

AFAIK, there is actually no totally clean solution to this. The best solution I found is to force push your local branch to your github branch (actually forcing a non-fast-orward update):

As per git-push(1):

Update the origin repository’s remote branch with local branch, allowing non-fast-forward updates. This can leave unreferenced commits dangling in the origin repository.

So don’t pull, just force push like this:

git push svg +user-non-unique

This will actually plainly overwrite your remote branch, with everything in your local branch. The commits which are in the remote stream (and caused the failure) will remain there, but will be dangling commit, which would eventually get deleted by git-gc(1). No big deal.

As I said, this is AFAICS the cleanest solution. The downside of this, is that your PR will be updated with those newest commits, which will get a later date, and could appear out of sync in the comment history of the PR. No big problem, but could potentially be confusing.


  • DieterVDW says:

    And this is why I will never recommend GIT to anyone…
    Too damn complicated, plenty of opportunities to fuck it up…

    Don’t get me wrong, I use GIT and I love it, but still waiting for something better to come along.
    I’ve seen intelligent teams trying to learn GIT on-the-fly, but that just isn’t possible.
    You really need to do quite a big upfront learning investment. And even then…

  • @80a9bd7f1cc273aa20463704a0f282f7:disqus

    I agree git is quite hard to learn. I have been occasionaly using it since about 4 years or so, and I am only now starting to understand it enough for most use cases. Migrating an organisation from say subversion to git is definitely not something to be taken lightly.

    But I love using it, and wouldn’t want to change. If you dislike the alternatives like bazaar or mercurial, and want to wait for something better, don’t hold your breath though 🙂

  • Wouter Verhelst says:

    uh, where’d you find that “+user-non-unique” thing? Doesn’t seem to be documented in the manpage. “git push –force” is, though, and is indeed the right thing to do.

    • RTFM git-push(1) 🙂

      The format of a parameter is an optional plus +, followed
      by the source ref , followed by a colon :, followed by the
      destination ref
      By having the optional
      leading +, you can tell git to update the ref even when the
      update is not a fast-forward. This does not attempt to merge
      into . See EXAMPLES below for details.
      git push origin +dev:master
      Update the origin repository’s master branch with the dev branch,
      allowing non-fast-forward updates. This can leave unreferenced
      commits dangling in the origin repository.

      –force is indeed nicer, though 🙂

  • Tom says:

    Thanks for this. Needed a guide that wasn’t trying to solve crazy edge cases like most StackExchange questions.