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.

Learn how to configure Mercurial to behave however you like.