This post is adapted from a GitLab Unfiltered blog post written by me, David O'Regan. In part one of our series, we explain the importance of fairness and empathetic thinking in code reviews.
Wanna know a
git secret? Patch files are magic when it comes to code reviews. A patch is a text file whose contents are similar to Git diff but along with code it contains metadata about commits, for example, a patch file will include commit ID, date, commit message, etc. We can create a patch from commits and other people can apply them to their repository.
A patch file is useful for code review because it allows the reviewer to create an actionable piece of code that shares their thoughts with the MR author. The code author can then apply the suggestion directly to their merge request. Patch files foster collaboration because it essentially creates a paired programming session in the review process.
One of the better examples of a simple patch file in action comes from Denys Mishunov, staff frontend engineer on the Create team.
To generate this suggestion, Denys pulled down the code he was reviewing and was able to offer a code solution based on his own testing. The patch file contains lots of valuable information, including the file affected, the date the revision was made, and the tool he used to generate the patch.
How to create a patch file
You can make a patch file using a web editor or with the command line. Read on to see how to create a patch file in GitLab both ways.
Patch files using a web editor
If you are rocking a nice fancy IDE or text editor, here's some good news: Most support patch files via plugins or out of the box. Here are some links to documentation on how to use patch files with different plugins: VSCode, Webstorm, Atom, and Vim.
Patch files using the command line
OK command line users, you’ve made some commits, here’s your
This command creates a new file,
reviewer_commit.patch, with all changes from the reviewer's latest commit against the feature branch:
```git format-patch HEAD~1 --stdout > reviewer_commit.patch``` ### How to apply the patch First, take a look at what changes are in the patch. You can do this easily with `git apply`: ```git apply --stat reviewer_commit.patch```
Heads up: Despite the name, this command won't actually apply the patch. It will just show the statistics about what the patch will do.
So now that we've had a look, let's test it first because not all patches are created equal:
git log and you can see the
Signed-off-by tag in the commit message. This tag makes it very easy to understand how this commit ended up in the codebase.
The benefits of patch files for code reviews
So now that you know how to make a shiny patch file, why would you use patch files as part of a code review process? There are a few reasons you might consider offering a patch file for a change you feel strongly about:
- It communicates you have invested a large amount of effort into understanding the author's solution and reasoning
- It demonstrates a passion for using teamwork to arrive at the best solution
- It shows the reviewer is willing to accept responsibility for this merge beyond just reading the code
There are a few alternatives to patch files for code reviews. GitLab has a suggestion feature which allows the reviewer to suggest code changes using Markdown in a merge request. The other option is to write raw code in Markdown right in the comment box. The downside is the reviewer doesn't have the option to test the code they are writing, making both of these options prone to error.
It is better to use a patch file because it involves the code reviewer in the review process in a collaborative way by default. In order to generate a patch, the reviewer must pull down the code, write the patch, test the change, and then submit it for the code author's consideration. Patch files increase the visibility for the reviewer and offers a fully collaborative experience for the code author.
Some people might argue patch files are a cheeky way for a reviewer to force a change they would rather see make it into the codebase, but I believe that anyone who has taken the time to check out a branch, run the project, implement a change, and then submits that change back for a discussion is fully embracing collaboration.
GitLab is evaluating whether to make patch files part of the code review and merge request workflow.
Learn more about the role of fairness in code review in part one of our blog series. Up next we explain why shipping small merge requests is in line with our iteration value.
“How to use patch files for code review” – David O’Regan
Click to tweet