Mercurial: The Definitive Guide

Understanding Patches

Because MQ doesn’t hide its patch-oriented nature, it is helpful to understand what patches are, and a little about the tools that work with them.

The traditional Unix diff command compares two files, and prints a list of differences between them. The patch command understands these differences as modifications to make to a file. Here is a simple example of these commands in action.

$ echo 'this is my original thought' > oldfile
$ echo 'i have changed my mind' > newfile
$ diff -u oldfile newfile > tiny.patch
$ cat tiny.patch
--- oldfile	2009-05-05 06:44:39.554480179 +0000
+++ newfile	2009-05-05 06:44:39.554480179 +0000
@@ -1 +1 @@
-this is my original thought
+i have changed my mind
$ patch < tiny.patch
patching file oldfile
$ cat oldfile
i have changed my mind

The type of file that diff generates (and patch takes as input) is called a “patch” or a “diff”; there is no difference between a patch and a diff. (We’ll use the term “patch” since it’s more commonly used.)

A patch file can start with arbitrary text; the patch command ignores this text, but MQ uses it as the commit message when creating changesets. To find the beginning of the patch content, patch searches for the first line that starts with the string diff -.

MQ works with unified diffs (patch can accept several other diff formats, but MQ doesn’t). A unified diff contains two kinds of header. The file header describes the file being modified; it contains the name of the file to modify. When patch sees a ...