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.

Index: app/assets/javascripts/projects/commits/components/author_select.vue
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
--- app/assets/javascripts/projects/commits/components/author_select.vue	(revision 697d0734f1ae469a9a3522838e36b435d7cdf0be)
+++ app/assets/javascripts/projects/commits/components/author_select.vue	(date 1589356024033)
@@ -110,6 +110,7 @@
     <gl-new-dropdown
       :text="dropdownText"
       :disabled="hasSearchParam"
+      toggle-class="gl-py-3"
       class="gl-dropdown w-100 mt-2 mt-sm-0"
     >
       <gl-new-dropdown-header>

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 git log:

git log --pretty=oneline -3

* da33d1k - (feature_branch) Reviewer Commit 1 (7 minutes ago)

* 66a84ah - (feature_branch) Developer 1 Commit (12 minutes ago)

* adsc8cd - (REL-0.5.0, origin/master, origin/HEAD, master) Release 13.0 (2 weeks ago)

``` javascript

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 apply --check reviewer_commit.patch```

If there are no errors we can apply this patch without worrying.

To apply the patch, you should use `git am` instead of `git apply`. The reason: `git am` allows you to sign off an applied patch with the reviewer's stamp.

git am --signoff &lt; reviewer_commit.patch

Applying: Reviewer Commit 1

``` javascript

Now run 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:

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.

30天免费试用极狐GitLab专业版

极狐GitLab不仅是源代码管理或CI/CD工具,它是一个覆盖完整软件开发生命周期和DevOps的开放式一体化平台。

免费试用
Git为Software Freedom Conservancy的注册商标,GitLab为GitLab B.V.的注册商标,我们已获授权使用“极狐GitLab”。

免费试用极狐GitLab 30天

有疑问? 联系我们

Gitlab x icon svg