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:
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:
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. (issue1076)
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. The internal:local and internal:other merge tools look like they do that, but only work if both branches have changed the content of the file. If the 'other' branch changes the file and 'local' does not, a merge using the internal:local tool will include that change, and vice versa. File renames, attribute changes and files added also suffer from this problem.
So to safely merge X into the current revision without letting any of the changes from X come through, do:
hg -y merge --tool=internal:fail X hg revert --all --rev . hg resolve -a -m
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. The -y option causes any questions that may come up to be answered in the affirmative, which is harmless since any changes will be reverted in the next step.
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.)
A faster way, using a command alias, assuming the source and dest are named branches:
[alias] mlog = log -r "children(ancestor($1,$2)):: and branch($1)"
and then
hg mlog source dest
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.
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:
.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, autohook.
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.
36. Restore file history after file move without rename
Steps:
- Update your working directory to before you did the rename
- Do an actual "hg rename" which will create a new head
- Merge that new head into the revision where you did the "manual" rename (not the head revision!)
- Then finally merge the head revision into this merge result.
Advice:
- Make a clone first and work on that, just in case!
- After finishing the steps, use a file compare tool to check that the original and the clone are identical
- Check the file history of any moved file to make sure it is now restored
37. View differences between a feature branch and latest ancestor of default
- hg update feature_branch
- hg diff -r 'ancestor(default,.)'
38. list files which might be affected by a merge
hg diff -r "ancestor(.,other) -r . --stat | cut -d "|" -f 1 | sed "s/ *$//" > /tmp/1 hg diff -r "ancestor(.,other) -r other --stat | cut -d "|" -f 1 | sed "s/ *$//" > /tmp/2 comm -12 <(sort /tmp/1) <(sort /tmp/2)
39. Beware of plain copying a Repo from Windows to Linux
In some cases, when no hg upstream server is present, one may copy e.g. an existing repository from Windows to Linux. However, Mercurial is sensitive to permissions. Any file that has been copied over from e.g. an NTFS drive gets its Executable attrribute set. Mercurial then treats such files as completely "new" in TortoiseHg (file view window, but 'M'-tagged) or via hg stat (however, a hg diff sees no difference between files in repo without 'x'-attribute and with 'x'-attribute in the workspace. A workaround is to update to tip (without backing up). This yields the desired state of all files.
40. Rename a branch (with the evolve extension)
In normal operation a named branch is permanent. With the EvolveExtension it can be renamed by changing the first commit which used the branch name (the root). To rename from O to N:
ROOT="$(hg id -qr 'first(roots(branch('$OLD')))')"
MSG="$(hg log -r $ROOT -T '{desc}')"
hg update $ROOT
hg branch $NEW
hg commit --amend -m "$MSG"
hg evolve --allNote that the EvolveExtension is still experimental! (more detailed version of this tip: Renaming a Mercurial branch with the evolve extension).