hgtip-content / beginner / 2009-09-30-configuring-mercurial.html

{% extends "_tip.html" %}
    title: Configuring Mercurial
    author_name: Steve Losh
    created: 2009-09-30

{% block excerpt %}
Learn how to configure Mercurial to behave however you like.
{% endblock %}

{% block tip %}

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:

    username = Steve Losh <>
    editor = vim
    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][hgrc-man].


### "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):


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

    username = Your Name <>
    editor = your_favorite_editor_command
    ... any extensions you like to use ...
    ... 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:

    username = Your Name <>

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:

    username = Your Name <>

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][hgrc-man] if you want to
know more.

{% endblock %}