Today we’re launching the beta of our brand new way to do better code review.

Butler Review is a commit based, chat centered review system built into the GitButler client.

It focuses on reviewing the evolution of individual commits within a branch, rather than a unified diff of the entire branch, allowing you to split up even large reviews into smaller, easier to review, better documented patches.

You can turn it on in the project settings of the GitButler Client and start using it today.

Ok, you get the gist, now let’s talk about what it is and why we built it.

Fifteen years ago I helped launch GitHub’s updated Pull Request system.

In that time, it’s become by far the most popular code review method in the world. Compared to how review was generally done before that, it has been an absolutely revolutionary tool.

However, there are some issues with the Pull Request model that have bugged me for the last decade.

The concept of reviewing the unified diff of all the commits in a branch seemed clever at the time, but I think we’ve all experienced the pain that this causes for larger or longer lived branches.

What is the difference between the last time I reviewed this and now? Why is the description in one tab and the code in another? There are 40 changed files, and the diffs are alphabetically ordered, how do I approach reviewing this monster?

In a nutshell, you know as well as I do that if someone sends you a PR with thousands of changed lines and dozens of changed files, you’re more likely to “LGTM” than spend hours trying to get through it.

Worse, if someone reviews your code and requests changes, this branch-based unified diff model encourages you to simply throw a crappy commit on the end that addresses the changes. How many “did some stuff” commits do you have in your codebase?

Even more worse, it’s difficult to work with someone on a branch. It’s incredibly cumbersome to work on a branch together, imagine trying to work on a commit together.

The Pull Request has not only hardly changed in principle since we launched it 15 years ago, but worse than that, nobody else has innovated beyond it since - GitLab’s Merge Requests, Bitbucket’s Pull Requests, everyone in this space has essentially copied that core concept without questioning it too much.

There have been commit-based systems like Gerrit and the defunct Phabricator which focus review on a single commit, but this results mainly in the squashing of everything that would be in a branch into one commit, thus often ending up similar to the end effect of the unified diff of a branch.

How can this process be improved? How can we make it easier to review larger code changes, easier to properly document our changes, easier to collaborate?

Today GitButler is launching our initial answer to this - Butler Review, a new tool for reviewing each other’s code that approaches the entire problem differently - by thinking of branches as a series of patches that evolve with feedback rather than as a single squashed changeset.

Butler Review is a commit based, chat centered review system where each commit in a branch is treated as an independently reviewable patch and the branch is seen as an evolving series of patches rather than a unified diff.

So how do Butler Reviews differ from the ubiquitous Pull/Merge Request?

• Commit based review
• Commit message as documentation
• Chat conversations around your patches
• Evolving patches
• Simple Interdiff
• Incremental review

In short, Butler Review lets you think about and review your commits as an evolving series of patches, where review is done as a chat based conversation around each one individually.

Ok, let's take a look at what all of this means.

The biggest change in focus with Butler Review versus the branch-based review of Pull/Merge Requests is that each commit is treated as an individually reviewable patch to the codebase.

If you have a branch that you’re working on that is getting larger and has thousands of changed lines and dozens of changed files, it can be difficult to review.

Instead of one large diff for your colleagues to try to grok, you can split it up into multiple, well documented changes that can be individually reviewed.

Reviewing 10 patches that are each semantically grouped 50 line changes is much easier than trying to understand one big 500 line diff.

This is inspired by the way mailing list based projects work, the collaboration method that Git was actually invented for. For example, if you look at how the Git project itself runs, it’s not via PRs, but instead via series of patches emailed to a list.

If there are suggestions for changes, the series is modified, re-rolled and resubmitted:

While mailing lists are difficult to use, I've always been inspired by the beauty and simplicity of reviewing and refining series of patches, rather than throwing slop commits on the top of a branch to address feedback.

One of the big issues with Pull Requests is that the commit message body is completely ignored, even hidden. There is no point writing anything beyond the first 50 characters of a message because it will never be seen during the review process.

With Butler Review, the commit message is always displayed at the top of your patch to help reviewers understand the context of what you’re trying to accomplish with the change.

There are several benefits to this.

The first is to break up what would have been stored in the PR description (at best) into contextual descriptions for each smaller logical change. The second is that this is actually stored in the git data, so if you run into this later with a blame, you can actually get good context as to why this change was made.

Annotating (blaming) code with Git in a PR-centric world is often almost useless because nobody writes good commit messages anymore, which is a logical consequence of making the message both unused during review and hidden.

Take a look at what a typical commit message looks like in a mailing-list centric workflow where commit messages are key to review context:

You will never see anything like this in a PR-based project, but with Butler Requests, this kind of message is much more likely to be written, since it is key to our review process.

Furthermore, unlike PR descriptions, these are in your Git data rather than in a proprietary database in the cloud.

The other huge difference we've made is using chat rather than comments as a way to more naturally discuss changes in our code.

Essentially, each commit becomes a proposed patch with it’s own real-time temporary chat room to discuss the changes. This is again inspired by the mailing list model, where each patch can be replied to in a thread, but much more usable.

What I’ve found in practice with review is that a PR is opened and then engineers will talk about the change in Slack or Discord. It’s real time, it’s less formal, it’s simple. Talk about the change or problem, come to a decision, then modify the code. However, now all that context is entirely lost.

By creating a small chat room for each patch, the conversations can be focused and fast. Also, gifs and emojis. 👍

Since the commit is the unit of review, when you get feedback, you will probably want to fix your original commits rather than add new commits to your branch. This way you don’t lose the context of the discussion around the change.

Most people don’t do this with PR based review because there is no advantage. Everything is squished together for review, so amending commits with proposed changes is functionally equivalent to throwing meaningless commits with helpful messages like “fix the stuff” on top.

Not only that, but with Git, it’s a bit painful and error prone to amend commits, especially ones that are a bit further back on the branch. Not everyone is comfortable with interactive rebasing and fixup commits.

With the GitButler client, however, all of this is very simple. Make the changes and drag them into the commit to amend it. Maybe edit the commit message. Then publish version 2 of the patch for incremental review.

With Butler Review, you’re much more likely to have 2 or 3 commits when you ask for your first round of review and even if it goes through a dozen versions, still end up with 2 or 3 (better) commits when you’re ready to merge it.

What happens if you have some feedback, amend several commits to incorporate that feedback and make those patches better, and then ask for further review?

Some of you may have PTSD from doing this with branch-based review systems - let’s just look at the entire unified diff again and figure out which 4 lines were changed since the last time I looked at it, right?

With GitButler Review, this isn’t a problem. You can easily view the interdiff between the last version you reviewed and the most current one by just clicking on the chat message that says there was a new version.

This doesn't show you differences on the whole branch, but at the commit level.

What is the difference between version 2 and version 4 of this commit? Not a problem, just click on the chat message saying a new version was published to see what was changed.

This breaks up even very large reviews into much more easily reviewable and better documented chunks.

Even more interestingly, with per-commit signoff, review now becomes incremental.

If you have a branch with 7 commits and you treat them as reviewable patches, once a patch is approved, you no longer need to pay attention to it. You can now just focus on the diminishing set of patches that still require changes.

Not only this, but you could also ask different people to review different commits. Now it’s possible to split up a branch into a few commits dealing with frontend changes and some dealing with backend changes and have multiple reviewers only focusing on the commits that require their expertise, even if all these changes need to be merged together.

If you want to move the review of some of your branches to Butler Review - perhaps your very large ones, for example - fear not for we have a great GitHub integration that will automatically keep your PR description up to date:

Internally at GitButler, we're using Butler Reviews for our patch based review and GitHub for our CI and mainline merging.

All of your GitButler client branches will show the status of both systems when review is enabled. You can choose to open either a Butler Review, a Pull Request, or both, for every branch you have.

Nope. The URLs that are generated for review are unlisted by default, but viewable by anyone with the URL.

Even if you are the only one using the GitButler client, you can generate review URLs and send them to anyone you want to get feedback from, which is easily done on the web with no client needed.

Enough blah blah, you should try it yourself if you think this is cool.

Butler Review is free and integrated into the newest release of the GitButler client.

To use it, just enable GitButler server features in your project settings and then click the new “Submit for Review” button on any branch. This will send those commits (and only those commits) to our server and give you a URL that you can share with anyone for feedback.

To respond to feedback and publish a new version, simply make the changes, create a new commit or drag the changes into existing commits, then hit “Push” again to publish a new version and continue the discussion.

GitButler Review is free for everyone, so try it out and let us know what you think in our Discord channel.

Let's all move beyond “LGTM”.