So what are the underlying problems which made this such a frequently requested feature? From reading the various links above, it seems that by far the biggest motivator is that people frequently submit pull requests (or merge requests, in GitLab-speak) which contain multiple commits, and these commits are seen as too “noisy” / fine-grained. In other words there is a desire to not pollute the target/trunk branch (e.g. master) with these fine-grained commits, and instead only have larger, less fine-grained commits merged.

But where does this desire come from? Well, if the fine-grained commits which accumulate on a PR branch are frequently amendments to earlier commits in the same PR (like “oops, fix typo I just made” or “oops, fix bug I just introduced”) then this desire is entirely understandable, because noone wants to see that kind of mess on master. However the real problem here is that that kind of mess should have never made it onto GitHub in the first place – not even onto a PR branch! It should have instead been fixed in the developer’s local repository. That is why there is a whole section in the “Pro Git” book dedicated to explaining how to rewrite local history, and why git-commit(1) and git-rebase(1) have native support for creating and squashing “fixup” commits into commits which they fix.

If an existing PR needs to be amended, make the change and then rewrite local history so that it’s clean. The new version of the branch can then be force-pushed to GitHub via git push -f, which is an operation GitHub understands and in many situations handles reasonably gracefully. I have previously blogged about why this way is better, but one way of quickly summarising it is: don’t wash your dirty linen in public any more than you have to.

In other words, if you do your history rewriting locally, there will be a substantial increase in the quality of what you publish to the PR, because you will only ever publish commits which (at the time) you believed to be the final candidate, ready for merging. (And later, when you benefit from the hindsight of peer reviews and/or your own realisations about how to make things better, you simply force-push a new final candidate.) Consequently, people reviewing your PR don’t have to waste time reviewing anything unless it was a candidate for merging, and nor do CI systems.

Granted, there are some exceptions to this approach, where you really do want to publish a PR which is still work in progress in order to get early feedback. In that case you can explicitly state in the PR description (or via a label) that this PR is WIP so that anyone reviewing it will know to expect some mess, and that’s totally fine.

Unfortunately, the force-push approach is not perfect either: the full history (a.k.a. reflog) of the PR branch is not exposed via GitHub’s UI, nor are there even guarantees that it will be preserved. This is one of GitHub’s serious flaws, which in contrast Gerrit gets right, and services integrating with GitHub such as https://reviewable.io/ and http://gerrithub.io/ can also help fill in the gaps here. The poor man’s workaround is to manually add comments every time you force-push, which explain what changed and how the changes address feedback from reviewers, but this of course requires discipline and extra effort, and does not show the exact changes, so it’s far from ideal.

These drawbacks with GitHub are another reason that some people prefer to append fixup commits to the PR and then squash at merge-time – at least then the history of the PR is visible to all. But this approach only works with PRs which represent a single logical change. If you squash multiple logical changes into a single commit, you lose valuable history. (In fact, this value can extend as far as using the history for literate programming.) So I strongly recommend keeping the GitHub repo configured with the default setting which allows normal merges, so that you don’t force this history loss on merge of PRs.

In response to the previous issue, you could decide a policy where you insist on clean commits and normal merging if the PR contains multiple logical changes, but allow unclean commits and squash merging if the PR contains only a single logical change. However the decision whether to do squash merge or normal merge is left to the merger, and it’s made at merge-time, outside the peer review process. So on a bigger project where many people have merge permissions, that reduces the chance of merges being done in a correct and consistent way.

By the way, I’m not the first person who has highlighted these problems.

OK sorry, that’s enough Star Wars quotes.

But this awkwardness highlights another fundamental issue with GitHub: it does not conveniently support “stacking” one PR on top of another, i.e. where the head of the first is the base of the second, with a dependency modelled between the two. (You can do it, but it’s awkward when the PRs come from different forks, and you also have to change the base branch of the second once the first is merged.)

So the only convenient way to group two dependent commits together is to put them in the same PR. This encourages the creation of PRs with many commits, which suck up more and more review effort each time their history is rewritten, and take longer to merge on average, because controversial and non-controversial commits tend to get mixed up within the same PR, and the former block the latter.

This is another area where Gerrit beats GitHub, since Gerrit natively supports dependencies between reviews, making the need for multiple commits per review redundant. Another advantage of this is that you don’t have to write a separate description for the PR, since all the info the reviewer requires is provided in a single commit message.

Anyway, I digress; back to squash merging. Another issue with it is that the final editing of the squashed commit message is after the review process, not during. If, like me, you work on projects which care deeply about the quality of the commit message, this is a deal-breaker.

Finally, the GitHub web UI doesn’t show when squash merging has been used, which can create confusion.

To wrap up, there is no perfect solution right now. However the following guidelines should help:

• Always adhere to best practice for constructing git commits.
• Try to keep your mess to yourself as much as possible, by rewriting history locally before publishing to or updating a GitHub PR.
• Squash merging will not work well for projects with stricter review policies, or projects which receive PRs comprising of multiple logical changes.
• Squash merging might work OK as a workaround for smaller projects with less stringent review policies, where PRs only ever consist of a single logical change which can reasonably be squashed into a single commit without harm.
• Keep PRs as small as possible, and aim for quick, short review cycles.

And in case the right people are listening:

• GitHub needs to track PR history and expose it through the UI.
• GitHub needs to support stacking of PRs (i.e. tracking dependencies between PRs, and correctly handling when a dependency gets merged).

A peer review cycle can potentially reveal many issues which make the pull request unready for merging, e.g.

• typos
• bugs in the proposed code changes
• missing features in the proposed code changes
• incomplete test coverage
• incomplete documentation changes
• style inconsistencies (including whitespace issues)
• incorrect or incomplete commit messages
• the commits violate the rule of one logical change per commit
• some changes are outside the scope of the pull request

This is of course what makes peer review of pull requests so valuable: the problems can be addressed even before they hit the master branch, which helps maintain high quality in the development trunk. But then how do we address the issues?

One approach is for the submitter fix the issues in their original local branch, close the pull request, and submit a new one. However in most cases this is a bad idea, because each time you do it, you create an “orphaned” abandoned pull request, and there is no automatic linking between the new revised one and the abandoned one, which makes it a lot harder to follow the history of the review process.

Another approach (the one apparently implied by the GitHub documentation mentioned above) is to append “fixup” commits to the series which fix issues introduced by commits earlier in the series. But that’s almost always a really bad idea, because again it violates the rule of one logical change per commit. In particular:

• It makes life much harder for reviewers, because they have to review a combination of broken commits and subsequent commits which are supposed to fix that brokenness. So for each change, they have follow this process:

  1. Review it as normal.
  2. If they spot brokenness, refrain from immediately commenting on it, and instead look ahead for any subsequent commit in the series which may claim to fix that brokenness.
  3. If such a commit is found, verify that it really does fix the brokenness.
  4. If it does fix it, selectively ignore that brokenness, whilst taking care not to accidentally ignore other brokenness in the same area.

  This problem is significantly compounded each review cycle, i.e. each time fixup commits are appended to the pull request.

  The only workaround is to review via the “Files changed” tab, but that brings considerable disadvantages when the pull request contains more than one commit, because then the reviewer cannot review individual logical changes one at a time.

• After merging the pull request, it pollutes the project’s history with useless noise: fixup commits which are not linked to the commits they are fixing.
• It breaks git bisect, git revert, and git blame.

The good news is that GitHub actually supports a much better alternative which works really nicely. As a maintainer and reviewer of many GitHub repositories, I’ve been continually surprised how many people are unaware of this simple trick; perhaps it’s due to the hole in GitHub’s pull request documentation which I mentioned above? The trick is simply this:

1. Rewrite the history of your local branch corresponding to the pull request, so that the issues revealed during the review of the pull request are addressed.
2. Do a force push (i.e. a git push command which includes the --force-with-lease option, not -f / --force which is dangerous and should never be used).

I won’t go into details here about how to rewrite history. git history rewriting via git rebase (with fixup, squash), git commit --amend etc. is something of an art form, and there are already many great resources out there which there would be no value in me replicating.

So really this whole blog post is a long way of saying:

When you force-push a new head for a pull request branch, GitHub handles it gracefully and automatically updates the pull request in the way you want.

It’s almost like magic. For example, if a reviewer commented on two hunks in the original pull request, and your force-push effectively rewrites one of those hunks but not the other, then the GitHub pull request UI will get updated to say something like “@reviewer commented on an outdated diff” for the rewritten hunk, but any outstanding review comments on the changed hunk will be presented as before the force-push.

Now don’t get me wrong – GitHub is not perfect. In some (but not all) ways, it is inferior to Gerrit’s review system which is better at exposing the complete history of the review cycle. I previously wrote another blog post examining GitHub’s review system in more depth. But in general, it’s usually plenty good enough.

If you’ve previously been fed the mantra “git force-push is evil, don’t ever use it”, or the more specific version “don’t ever force-push to public branches” then hopefully you now realise neither are correct. There are many perfectly valid use cases for force push, otherwise the extremely clever developers who implemented it wouldn’t have bothered (and let’s face it, they know far more about git than you or I ever will). Ultimately the validity / safety of doing a force push to a public branch depends on the audience’s expectations for the stability of that branch. If people expect it to be stable and never get rewritten (only fast-forwarded), then you shouldn’t force push, or at least not without a decent effort to correct those people’s expectations. However there is generally no reason why people should expect GitHub pull request branches to be stable, because people generally don’t base other branches on top of them.

The article entitled “The Dark Side of the Force Push” may help further your understanding.

Note that the title of the previous sections referred to your existing pull requests. GitHub doesn’t let you amend anyone else’s pull requests, and that’s a good thing for obvious reasons. But what if one developer submits a pull request, vanishes off on holiday, and whilst they are away, it gets reviewed and issues are revealed?

In this case it’s easy to effectively take over the process. Simply create a local branch which points to the same commit as the head of the pull request. If you have the totally awesome hub CLI tool installed, then this is as simple as:

git checkout https://github.com/github/hub/pull/134

Then amend your branch as necessary according to the existing reviews, and submit a new pull request which references the old pull request it’s superceding, either by URL or by number. You will probably also want to arrange for the old pull request to be closed with a comment linking to its successor.