Writing hgrc

Mercurial is a great distributed SCM (Source Control Management) system. It is easy for me to use, meaning it's great for beginners. I've also heard that it has more advanced functionality for the advanced user, most of which I do not use. If you are using Mercurial with Oh! No! Publishing, you may not want to read this article.

Writing a .hgrc

Each .hgrc file is organized into multiple sections. To find detailed information about each one, see hgrc(5). Each section is preceded by the name of the section inside of square brackets (e.g., [section]). Each option gets its own line and is specified by writing its name followed by and equal sign followed by its value. The following is an example section with one option set:

[ui]
username = Nathan Phillip Brink <jsmith@ohnopublishing.net>

User's .hgrc

Every user has his or her own .hgrc file. If you are using a standard UNIX-like OS, such as GNU, you will most likely be able to access the file at the following path:

~/.hgrc

Inside of this file, you should specify the username option of the ui section. Otherwise, the nickname hg records in Mercurial's changelog every time you commit will be set to your username@hostname. See ex1 for how to set your username option. What you set as your username is completely up to you, but you should follow the convention. Format your username as and email address, i.e. Real Name <user@example.org>.

Repo's hgrc

Each repository also has an hgrc file. It is named .hg/hgrc inside of each repository. But this file is not transported with the repository because each user may have different settings for each copy of the repo. There are a few settings in the paths section that are worth note:

1. default: the URL/URI of where Mercurial will try to download updates to your repository when you run $ hg pull and don't explicitly specify a repository from which to pull. When you first clone a repository, Mercurial will automatically set default to the URI of the repository you cloned.
2. default-push: the URL/URI of the repository which Mercurial will try to upload your changes to when you run $ hg push and don't specify a destination repository. If this option is not set, Mercurial will use the value of the default option.

I often use both of these variables because I have repositories published publicly at /hg/ and I edit them. I can pull from the publicly accessible repos with ease over HTTP. However, I cannot push because my HTTP repos are not writeable. I have not set up HTTP-based authentication because that would require more work and learning and using Kerberos or publickey authentication over ssh is more secure. So I instead push to the URI ssh://hg.ohnopub.net//home/hg/repos/projectname (notice the double forward-slash, because the path is not relative to my home directory). For my project named makeldif, I've set up the following .hg/hgrc file:

[paths]
default = http://hg.ohnopub.net/hg/makeldif
default-push = ssh://hg.ohnopub.net//home/hg/repos/makeldif

Remember that for pushing and pulling against locally accessible repos, you may just specify a directory name rather than a full URI. The following example assumes that you somehow have a shell on ohnopub.net and are able to push to the repository locally:

[paths]
default = /home/hg/repos/makeldif