Appendix A
Command reference

A.1 “hg add”—add files at the next commit

--include, also -I

--exclude, also -X

--dry-run, also -n

A.2 “hg diff”—print changes in history or working directory

Show differences between revisions for the specified files or directories, using the unified diff format. For a description of the unified diff format, see section 12.4.

By default, this command does not print diffs for files that Mercurial considers to contain binary data. To control this behaviour, see the -a and --git options.

A.2.1 Options

--nodates option

Omit date and time information when printing diff headers.

--ignore-blank-lines, also -B

Do not print changes that only insert or delete blank lines. A line that contains only whitespace is not considered blank.

--include, also -I

Include files and directories whose names match the given patterns.

--exclude, also -X

Exclude files and directories whose names match the given patterns.

--text, also -a

If this option is not specified, “hg diff” will refuse to print diffs for files that it detects as binary. Specifying -a forces “hg diff” to treat all files as text, and generate diffs for all of them.

This option is useful for files that are “mostly text” but have a few embedded NUL characters. If you use it on files that contain a lot of binary data, its output will be incomprehensible.

--ignore-space-change, also -b

Do not print a line if the only change to that line is in the amount of white space it contains.

--git, also -g

Print git-compatible diffs. XXX reference a format description.

--show-function, also -p

Display the name of the enclosing function in a hunk header, using a simple heuristic. This functionality is enabled by default, so the -p option has no effect unless you change the value of the showfunc config item, as in the following example.

--rev, also -r

Specify one or more revisions to compare. The “hg diff” command accepts up to two -r options to specify the revisions to compare.

1. Display the differences between the parent revision of the working directory and the working directory.
2. Display the differences between the specified changeset and the working directory.
3. Display the differences between the two specified changesets.

You can specify two revisions using either two -r options or revision range notation. For example, the two revision specifications below are equivalent.

When you provide two revisions, Mercurial treats the order of those revisions as significant. Thus, “hg diff -r10:20” will produce a diff that will transform files from their contents as of revision 10 to their contents as of revision 20, while “hg diff -r20:10” means the opposite: the diff that will transform files from their revision 20 contents to their revision 10 contents. You cannot reverse the ordering in this way if you are diffing against the working directory.

--ignore-all-space, also -w

A.3 “hg version”—print version and copyright information

This command displays the version of Mercurial you are running, and its copyright license. There are four kinds of version string that you may see.

• The string “unknown”. This version of Mercurial was not built in a Mercurial repository, and cannot determine its own version.
• A short numeric string, such as “1.1”. This is a build of a revision of Mercurial that was identified by a specific tag in the repository where it was built. (This doesn’t necessarily mean that you’re running an official release; someone else could have added that tag to any revision in the repository where they built Mercurial.)
• A hexadecimal string, such as “875489e31abe”. This is a build of the given revision of Mercurial.
• A hexadecimal string followed by a date, such as “875489e31abe+20070205”. This is a build of the given revision of Mercurial, where the build repository contained some local changes that had not been committed.

A.3.1 Tips and tricks

Why do the results of “hg diff” and “hg status” differ?

When you run the “hg status” command, you’ll see a list of files that Mercurial will record changes for the next time you perform a commit. If you run the “hg diff” command, you may notice that it prints diffs for only a subset of the files that “hg status” listed. There are two possible reasons for this.

The first is that “hg status” prints some kinds of modifications that “hg diff” doesn’t normally display. The “hg diff” command normally outputs unified diffs, which don’t have the ability to represent some changes that Mercurial can track. Most notably, traditional diffs can’t represent a change in whether or not a file is executable, but Mercurial records this information.

If you use the --git option to “hg diff”, it will display git-compatible diffs that can display this extra information.

The second possible reason that “hg diff” might be printing diffs for a subset of the files displayed by “hg status” is that if you invoke it without any arguments, “hg diff” prints diffs against the first parent of the working directory. If you have run “hg merge” to merge two changesets, but you haven’t yet committed the results of the merge, your working directory has two parents (use “hg parents” to see them). While “hg status” prints modifications relative to both parents after an uncommitted merge, “hg diff” still operates relative only to the first parent. You can get it to print diffs relative to the second parent by specifying that parent with the -r option. There is no way to print diffs relative to both parents.

Generating safe binary diffs

If you use the -a option to force Mercurial to print diffs of files that are either “mostly text” or contain lots of binary data, those diffs cannot subsequently be applied by either Mercurial’s “hg import” command or the system’s patch command.

If you want to generate a diff of a binary file that is safe to use as input for “hg import”, use the “hg diff”–git option when you generate the patch. The system patch command cannot handle binary patches at all.