Creating an interdiff

Last updated on
1 December 2022

What is an interdiff and why it is useful?

An interdiff is a text file in patch format that describes the changes between two versions of a patch. Using interdiffs is a best practice that saves time and reduces tedium for reviewers by allowing them to focus on just the changes introduced in patch iterations. You should supply one whenever you update a patch in an issue, but make sure that you always upload the full patch too).

Example:
interdiff-screenshot.gif

Create interdiff using drupalorg-cli

You can use the drupalorg command-line tool to create an interdiff. See the documentation at the drupalorg-cli tool page on GitHub for more information.

Create interdiff using Dorgflow

Dorgflow is a command that gets a Drupal issue's patches and helps create an interdiff. See the documentation at the Dorgflow GitHub page.

Create interdiff using patchutils

You can create interdiffs by using the interdiff command that is included with patchutils.

interdiff old.patch new.patch > interdiff_[old_comment_number]-[new_comment_number].txt

For Mac-users: the easiest way to get the interdiff command available is by using Homebrew with the following command: brew install patchutils

For Debian-ish Linux-users: Install it with: sudo apt install patchutils

Create interdiff using Git

Approach using a single Git branch

  1. Follow the steps on Apply a patch to a feature branch to update your local environment, create a feature branch, and apply the previous patch.
  2. Commit the previous code to your feature branch.
  3. Make your new changes locally.
  4. Make a diff file between the HEAD revision (with your changes) and the previous commit:
    git diff HEAD~1 > interdiff_[old_comment_number]-[new_comment_number].txt
    Alternatively, if you have made (for example) 3 local commits since the previous patch, you can use this command:
    git diff HEAD~3 > interdiff_[old_comment_number]-[new_comment_number].txt

Approach using two Git branches

  1. Always pull the latest changes.
    git pull --rebase
  2. Create a branch for the old patch.
    git checkout -b [issue_id]-[old_comment_number]
  3. Download the old version of the patch you wish to update and apply it to your local git repository.
    git apply --index patchname.patch
  4. Commit the changes from the old patch.
    git commit -m "[issue_id]-[old_comment_number]"
  5. If you do not yet have a new patch created, create a new branch based on the old patch's branch.
    git checkout -b [issue_id]-[new_comment_number]

    If you have already created your new patch, go back to the mainline branch and create a new branch to patch from.
    git checkout 8.0.x
    git checkout -b [issue_id]-[new_comment_number]

  6. Make your changes on the new branch (apply your new patch or edit the code). Commit the changes.
    git commit -am "[issue_id]-[new_comment_number]"
  7. Generate the interdiff by comparing the current (new) branch against the old branch.
    git diff [issue_id]-[old_comment_number] > interdiff_[old_comment_number]-[new_comment_number].txt

Why use interdiff and not just simply diff two patches?

An interdiff tells you whether lines removed in the second patch were added in the first patch, and similarly, whether lines added in the second patch were removed in the first patch. Simply diffing the two commits does not provide this information, forcing the reviewer to consult the original patch or current source to determine whether this is the case.

Exception: Rerolled patches.

Make interdiff ignored by the testbot

Use .txt extension for interdiff. Final pattern will be interdiff_[old_comment_number]-[new_comment_number].txt.
For example: interdiff_91-92.txt

What am I supposed to do with another user's interdiff?

Nothing, other than read it. Interdiffs are for developers and reviewers working on a patch, not for site builders using the patches. They help to easily see the differences between two versions of a patch.
It is easy to tell which files are patches you can use and which are not by the file extension. The real patches end in .patch and they are the only ones you should try to apply to your site.

What about rerolled patches?

(What does rerolling mean? See Rerolling patches.)

You can't create an interdiff of a rerolled patch -- here's why:
Depending on which method you use to create an interdiff, it's assumed that both versions of the patch can apply cleanly to the same version of the file(s) being patched, OR, it's assumed that there are no changes to the repository other than the changes made by the patches. But, if those assumptions were the case, the patch wouldn't need to be rerolled!

That said, it's still helpful to provide details about the change(s) to the patch. In this case, you can do a simple diff of the two files, and post that diff along with your rerolled patch. It's not considered a requirement, but it's certainly nice to have! Example:
diff -u old.patch new.patch > reroll_diff_[old_comment_number]-[new_comment_number].txt

More information

See also Interdiffs! How to make them, and why they are your friends.

Tags

Help improve this page

Page status: No known problems

You can: