Tips and Tricks

(see also FAQ, HOWTOs, CategoryTipsAndTricks)

1. Undo an '`hg add`'

If you have accidentally added a file, the way to undo that (changing its status from A back to ?, or unknown) is 'hg revert'. For example, if you just ran 'hg add' and realized that you do not want files foo or bar to be tracked by Mercurial:

hg revert foo bar

If you want to revert all pendings 'add's, at least on Unix you can use this trick:

hg status -an0 | xargs -0 hg revert

2. Save a push URL so that you don't need to enter it each time

It is possible to store a default push URL that will be used when you type just 'hg push'. Edit hgrc and add something like:

[paths]
default-push = ssh://hg@example.com/path

3. Track changes to a repository with RSS

You can track changes to projects and individual files with RSS feeds from hgweb. Here are some examples:

• http://selenic.com/hg/rss-log/

• http://selenic.com/hg/rss-log/tip/mercurial/hgweb/hgweb_mod.py

4. Create links to snapshots of files and tarballs

If you want to create web links to tagged or tip versions of a repository or a file, you can do so like this:

• http://selenic.com/hg/archive/tip.tar.gz

• http://selenic.com/hg/archive/0.9.3.zip

• http://selenic.com/hg/raw-file/tip/COPYING

• http://selenic.com/hg/raw-file/0.9.3/COPYING

Be aware though that tarballs require some configuration to work; add this to .hg/hgrc of repository (or to your '--webdir-conf'):

[web]
allow_archive = gz zip

5. Configuring Mercurial

See in .hgrc.

6. Abbreviate command options

It is possible to abbreviate command options:

hg revert --no-b
hg revert --no-backup

7. Ignore files from Emacs/XEmacs

Add the following to .hgignore:

syntax: glob
*~

syntax: regexp
(.*/)?\#[^/]*\#$

8. Ignore files in local working copy only

Add the following to the repo's .hg/hgrc:

[ui]
ignore = /path/to/repo/.hg/hgignore

and create a new file .hg/hgignore beside it. This new file will be untracked, but work the same as the versioned .hgignore file for this specific working copy. (The /path/to/repo bit is unfortunate but necessary to make it work when invoking 'hg' from within a subdir of the repo.)

9. Make a clean copy of a source tree, like CVS export

cd source
hg archive ../export

or you could simply clone the repository and remove the .hg folder:

hg clone source export
rm -rf export/.hg

To export a tagged release:

cd source
hg archive -r mytag ../export-tagged

10. One liner to remove unknown files with a pattern

Mercurial ships with the PurgeExtension for that purpose:

hg purge -p pattern

lists the files that will be removed. Remove the '-p' option to really removed the matched files.

If you need finer control, you can pipe the output of 'hg st -un' through your favorite commands.

11. Customize diff behavior

11.1. Generating color diff output

You can just enable the ColorExtension to colorize command outputs. It has been bundled with Mercurial since 1.1

11.2. Use a custom diff program

To get colors for pre-1.1 Mercurial, you can use the extdiff extension with the 'colordiff' tool to get colorized diff output. If you've enabled the extension and have 'colordiff' installed, the following hgrc snippet will create a new 'hg cdiff' command:

[defaults]
# suppress noisy extdiff header message
cdiff = -q

[extdiff]
cmd.cdiff = colordiff
opts.cdiff = -uprN

Similarly, on OSX if you want to use 'FileMerge.app' for your diffs, you can use the ExtdiffExtension. The provided command-line wrapper 'opendiff' for 'FileMerge.app' will not work directly with the extension, but you can instead use the script fmdiff which wraps 'FileMerge.app' so that it responds like the usual diff program. Once 'fmdiff' is in your path, just add the following to your .hgrc file

[extensions]
hgext.extdiff =

[extdiff]
cmd.opendiff = fmdiff

and use

$ hg opendiff ...

12. Using environment variables in hgrc files

You can use environment variables in filenames read from hgrc files with Mercurial 1.4. This applies to paths used to enable extensions and the paths used to load ignore files:

[extensions]
foo = $MYEXTENSIONS/foo.py

[ui]
ignore = $MYIGNORE

13. Using Vim as the filemerge program

The Vim text editor provides a graphical diff feature. To resolve Mercurial merge conflicts using Vim, add the below to your .hgrc file:

[merge-patterns]
** = filemerge

[merge-tools]
filemerge.executable = gvim
filemerge.args = -d $local $other
filemerge.checkchanged = true
filemerge.gui = true

14. Using RCS merge as the filemerge program

The 'merge' program supplied with 'RCS' gives more complete conflict markers than the default install if you give it the -A option. For your .hgrc:

[merge-tools]
filemerge.executable = /usr/bin/merge
filemerge.args = -A $local $base $other

See also MergingManuallyInEditor.

15. hg diff does not support -foo option like gnu diff does

I use the following bash function to put the diff options I like most

hgdi ()
{
  for i in `hg status -marn "$@"`
  do
    diff -ubwd <(hg cat "$i") "$i"
  done
}

You can also use the ExtdiffExtension to call GNU 'diff' from Mercurial.

16. Handling binary files

As stated in BinaryFiles, you need to have a tool which manages binary merge. Newer versions of Joachim Eibl's KDiff3 program (using Qt 4, known on Windows as 'kdiff3-QT4.exe') recognize binary files. Pressing "cancel" and "do not save" leaves you with the version of the file you have currently in the filesystem. See also on CvsConcepts.

17. Diagnose "abort: Error" messages

I get a cryptic "abort: Error" message while pushing to my server. This is not enough info to figure out the problem. I tried 'hg -v --debug push' but I still don't get anything more informative. What can I do?

• disable cgitb in hgweb on the server

• run with '--debug --traceback' on the client

• check the error logs on the server

18. Removing the working directory of a repository

If you forgot to specify -U on 'hg clone', doing

hg update null

will remove everything from the working directory of the repository. See also update. (reference)

19. Setting the default context for diff to something larger

'hg diff' outputs 3 lines of context per default (see 'hg help diff'). To change the default to for example 8 lines, add

[defaults]
diff = --unified 8

to the defaults section of your .hgrc. However, this only affects the diff command itself. (reference)

20. Find repositories with GNU find

Users with access to GNU find may find these one-liners useful for managing all their repositories at once. They can of course be added to shell scripts to do more interesting things.

Print a list of directories which have repositories (a directory called .hg exists):

find ~/ -name ".hg" -type d -execdir pwd \;

Print a list of tracked files too:

find ~/ -name ".hg" -type d -printf "\t" -execdir pwd \; -execdir hg status -c -m -a -d \; -printf "\n"

21. Change temporary directory used on remote when pushing

See description of a hook for changing tmp directory on remote when pushing.

22. Keep "My" or "Their" files when doing a merge

Occasionally you want to merge two heads, but you want to throw away all changes from one of the heads, a so-called dummy merge. You can override the merge by using the ui.merge configuration entry:

$ hg --config ui.merge=internal:local merge  #keep my files
$ hg --config ui.merge=internal:other merge  #keep their files

Here local means parent of working directory, other is the head you want to merge with. This will leave out updates from the other head.

However, note that files added in the other head wont cause a conflict, and therefore no merging will be done. To merge X into the current revision without letting any of the changes from X come through, do:

hg --config ui.merge=internal:fail merge X
hg revert --all --rev .

This will ensure that only changes from the current working copy parent revision are committed when you commit the merge.

Using internal:fail will fail the merge - this is useful if you want to prevent Mercurial from starting a merge tool after a merge with conflicts.

23. Split a subdirectory into a separate project

Use ConvertExtension with --filemap option.

24. Use an extension only for one call (without editing hgrc)

You can enable an extension only for this call of 'hg' by setting '--config'.

This enables the mq extension and calls its strip command to remove revision 111:

hg --config extensions.hgext.mq= strip 111

25. Convert a repo with mixed line endings to LF only

Enable the Win32TextExtension with encoding only.

Snippet of hgrc:

[extensions]
hgext.win32text=

#encode only => only LF in repo
[encode]
** = cleverencode:
[decode]
#** = cleverdecode:

Update the working directory. To force the update to all files do 'hg update null' first and then 'hg update [rev]'. The line endings in the working directory are still the same as in the repo.

Commit the changes. All the line endings are converted to LF before committing. To see the changes in the working dir do 'hg update null' and 'hg update [tip]' again.

(To convert all the line endings to CRLF, enable decode only).

26. Log all csets that would be merged (emulate '`hg incoming`' for merges)

Say you are considering merging from source to dest and you want to know which changesets will be involved, i.e. what's in source that's not in dest. In graph terms, you want to see all the ancestors of source (including source itself) that are not also ancestors of dest. (If source is already an ancestor of dest, then there is nothing to merge.)

This command will work on all versions of Mercurial, although it's slow with large repositories:

hg log -r 0:source --prune dest

(To omit merge csets, add -M.)

In Mercurial 1.4, 'merge' grew a '--preview' option that was intended to do the same thing more conveniently. The 1.4 version of 'merge --preview' doesn't actually show all the changesets that will be merged, but that bug was fixed in 1.5. So if you are using Mercurial 1.5 or later, you can get the same answer faster with

hg update dest
hg merge --preview source

(There is no way to omit merges with 'merge --preview'.)

27. Import all patches in a mbox file

The 'hg import' command only accepts a single patch, but the 'formail' tool (comes with procmail) can be used to split them:

formail -s hg import - < yourmailbox.mbox

This imports all emails with patches, skips those that don't, and works with inline or attachment patches.

28. Avoid merging autogenerated (binary) files (PDF)

Usecase: Writing in LaTeX, but always having an up to date pdf in the working dir.

There are two main options:

1. Not merging pdfs (UNTESTED):

For this you just choose a merge tool for pdfs which simply keeps either your or the other version.

Edit your .hg/hgrc to include the following section:

[merge-patterns]
**.pdf = internal:local #keep my files
**.pdf = internal:other #keep their files

(you should only use one of the lines)

This way all PDFs will always be either at your revision or the other revision and you won't have (real) merges.

- MergeToolConfiguration

2. Creating pdfs on the fly

This assumes that you always want to have the PDFs you can use, but that you don't need to track them - only their contents (and those are defined in the tex files).

For this you add an update hook which crates the pdf whenever you update to a revision.

Edit your .hg/hgrc to include the hooks section with an update hook:

[hooks]
update.create_pdfs = latex your_tex_file.tex

To make this still a bit easier, you can use a versioned script which creates all pdf. that way you can just call the script and don't need to worry about editing the .hg/hgrc when you add text files or change the call.

I use a python script for platform compatibility:

parse_latex.py:

from subprocess import call
for i in ("file1.tex", "file2.tex"):
  call(["latex", i])

.hg/hgrc:

[hooks]
update.create = ./parse_latex.py

- http://hgbook.red-bean.com/read/handling-repository-events-with-hooks.html

29. Specify Explicit Ssh Connection Timeouts

If in an unattended script you want to explicitly timeout connection attempts in the case of a misbehaving server or network you can do:

hg push --ssh "/path/to/ssh -o ConnectTimeout=10"

Where the value for ConnectTimeout is in seconds. ConnectionAttempts is also available to specify a number of retries (default is none).

30. Fake A Commit Message Template In VIM

Presumably this can be done with any scriptable editor. Place this in your ~/.hgrc:

editor = /usr/bin/vim -c "r ~/.hgtemplate"

Create a template in ~/.hgtemplate. Example:

Bug: XXXX
Reviewed by: XXXX

31. Prevent a push that would create multiple heads

In many Mercurial work flows, teams may have a stable or master tree that is supposed to have only one head. While a plain 'hg push' will warn you if you're going to create new heads, that is merely a warning on the client side intended to help/remind users that they may have forgotten to merge first. However, 'hg push -f' will let you do a push that does create new heads (this is also very common usage for sharing changes via "working" or "review" or ... Mercurial repos). The only way to protect a repo from multiple heads is by using a hook that runs in the repo-to-be-protected. There are several existing hooks that do that which may be useful to copy and adapt: Netbeans, Mozilla, David Herron's (bash) hook, the Headcount hook.

32. Check If One revision Is A Descendant Of Another

function isKid() {
  if [ $(hg debugancestor $1 $2 | cut -d : -f 1) == "$1" ] ; then
    echo $2 is a decendent of $1;
  else
   echo $2 is NOT a descendent of $1;
  fi
}

Example:

$ isKid 70 72
72 is a decendent of 70

$ isKid 72 70
70 is NOT a descendent of 72

33. Merge or rebase with uncommitted changes

It is not possible to merge or rebase when there are uncommited local changes in the working copy. Some recommend using the shelve extension or mq to handle that, but there is an even easier way. First put your local changes in a patch file, then revert the changes in the working copy.

hg diff > somefile # save local changes

hg revert -a       # nuke 'em

Now you can do your merge or rebase in your clean working copy.

When you're done you reapply the changes again:

hg import --no-commit somefile

Originally described by Matt on the users list.

34. Remove files that are matched by .hgignore but were added in error

If there are only a few files they can easily hg removeed manually. If many files were already added to the repository before e.g. .hgignore is changed then the following trick might help.

The files matched in .hgignore already added to the repository will not show in a 'hg status -i' since only files not already in the repository are ignored. Solution is to have a temporary pristine repository to find all ignored files:

hg clone source temp
cd temp
rm -rf .hg
hg init

In temp/ we have now a tree of all files in the source/ repository but not being added to the newly created empty repository.

hg status -i

will show now all files ignored by .hgignore but in the original repository. This list can be massaged in a editor to create a bunch of 'hg remove' lines. This can be further automated by using

cd temp
hg status -in0 | xargs -0 hg --cwd ../source remove

Explanation: 'hg status -in0 'produces a zero delimited list of all ignored files without the I prefix. This list is consumed by 'xargs -0' calling 'hg remove' in the original repository ('--cwd ../source').

The directory temp can then be discarded.

This trick was the idea of MartinGeisler on #mercurial

35. Check for tabs or trailing whitespace before commit

Check out the checkfiles extension which installs a hook to do just that.

Given --verbose, it also points out where on each line tabs or trailing whitespace is.

The file extensions to check is configurable in your hgrc, as well as a list specific files to exclude from the check.