Configuring Mercurial
posted by Steve Losh on September 30, 2009
Mercurial’s behavior is controlled by a couple of plain old text files. Let’s take a look at each these files and see how they work.
Config File Format
Mercurial’s config files are broken up into sections. Each section can have several entries. For example:
[ui]
username = Steve Losh <steve@stevelosh.com>
editor = vim
[alias]
killitwithfire = revert --no-backup --all
This sample file has two sections: [ui] and [alias]. The [ui] section
has two entries and the [alias] section has one entry. The name of each
entry is to the left of the equal sign, the value is to the right.
You can edit the config files with any text editor you like.
Config File Levels
Every time you run Mercurial it looks in a couple of different places for config files and applies the settings from all the files it finds. Settings in more “specific” config files will override settings in more “general” files. We’ll see learn what “specific” and “general” mean as we go along.
“Install-wide” and “System-wide” Config Files
These are the most general config files you’ll find. Any settings inside these files will apply to every user running in any directory.
You probably won’t use them very much unless you’re administering a multi-user system. For now, we’ll ignore them. If you want to learn more, check out the man page.
“User-wide” Config Files
Each user on a system can have a Mercurial config file just for them. These files are more “specific” than the install-wide and system-wide files, and they’re the config files you’ll be using most of the time.
On UNIX, Linux, OS X systems your personal config file is located at
$HOME/.hgrc (aka ~/.hgrc).
On Windows it can be in any of the following locations (you can pick one you like and create the file):
%HOME%\Mercurial.ini
%HOME%\.hgrc
%USERPROFILE%\Mercurial.ini
%USERPROFILE%\.hgrc
Settings in this file will override settings of the same section/name combination in the install-wide and system-wide config files.
This is the place to put all the settings specific to you as a user. For example:
[ui]
username = Your Name <your@email.com>
editor = your_favorite_editor_command
[extensions]
... any extensions you like to use ...
[alias]
... any aliases you find convenient ...
“Repository-wide” Config Files
These are the most “specific” config files, and the settings inside of them only apply to commands run on the repository they’re inside of.
The location of a repository-wide config file is always:
[repository-path]/.hg/hgrc. Be careful, that’s hgrc with no dot in
front of it!
Why would you want to specify settings just for a single repository? A common example is when you want to use a different email address when committing to a certain repository.
You might have a user-wide config file that contains this:
[ui]
username = Your Name <you@personal.com>
But for a specific repository you might want to use your work email, so you
would put this into the [repository-path]/.hg/hgrc file for that repository:
[ui]
username = Your Name <you@work.com>
Now when you commit to that repository it will use your work email address, because the repository-wide config file is more specific than the user-wide config file and overrides it.
Who Does Mercurial Trust?
As you start to use Mercurial more and more, you may eventually run into error messages that look like this:
Not trusting file /home/alice/repo/.hg/hgrc from untrusted user alice, group users
When you see a message like this, Mercurial is telling you that there’s an
hgrc file that it would normally use, but it’s owned by someone else that may
have made nefarious changes to it.
To learn more about this situation you should take a look at the Trust page on the Mercurial wiki.
Learn More
This tip just showed you where to find config files and how to edit them. There’s a lot more information on the hgrc man page if you want to know more.