I Beg to Difr

The poor-man's code review solution

Code reviews are good. The best reviews are the ones where you're sitting directly next to whoever wrote the code. However, you don't always have that luxury. In some cases, the code was written by somebody on the other side of the globe. In those cases, having a tool that allow syou to capture your finds would be really convenient.

What's out there?

There's plenty of stuff out there. However, none of the tools out there actually served my purpose:

  • In some cases, it's too expensive. It just is. And what's worse: in order to justify the price tag, the vendor started adding feature that I don't even care about. Stuff that gets in the way. I don't want them to solve a workflow problem, I want them to make it easier to share my review results. (Crucible and Cahoots fit in this space.)
  • In other cases, it requires everybody to use the same tools. IntelliJ has a bunch of plugins, but those plugins would only be useful if every member of your team uses IntelliJ. Other than that, the IntelliJ plugin requires you to store the XML file with the review results in your code base. Not quite what I'm looking for.
  • There's more free software. I tried Barkeep. It looks pretty cool, but you need a server to host it, installation is only trivial on a system that you don't intend to use for anything else, but then there's no way to enforce access control. With Barkeep, everybody can just walk in. Again, not quite the feature I'm looking for.
  • GitHub itself allows you to add comments to the source code. However, it doesn't allow you to comment on a diff between branches, and with every comment, it seems the entire team gets notified. A bit too verbose for my taste.

Difr to the rescue

Yesterday, I just got fed up with looking for the right tool. If it's not out there, then surely I can create something simple myself. And behold, I present to you: difr (= diff review).

How does it work? It's quite easy actually. You need a diff. That's where it all starts. Then you pass that diff through the difr command. That will produce an HTML version of the diff, not unlike the HTML view of the diff GitHub produces. There's one difference though. The HTML view embeds an editor for adding annotations.

Difr in action

If you open the HTML file produced in your browser, then clicking a line allows you add a comment on that line. Once you hit ENTER, that comment will be stored in the page.

Where's the routing?

It's not there. If you want to send the results back to your co-worker, then you could either

  • Copy the current state of the editor and paste it into an email (Gmail will preserve the formatting), or
  • Save the current review as an HTML file and send that to your co-worker as an attachment.

How to do it?

In the examples below, I'm using bcat to send the difr output to a browser. You could also just store it first and then open that file.

Not committed diff

git diff | difr | bcat

Feature branch diff

git flow feature diff horsing-around | difr | bcat

Tell me more

There's not too much more information available just yet, but you might be interested to check out the demo: