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 want to read this article.

Writing a .hgrc

Each .hgrc file is organized into multiple sections. To find detailed information about each one, see the manpage of hgrc. 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 others will have higher respect of your commits if you try to keep your username constant and use your real name (unlike me, though I use my email address which is probably good enough).

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

2. default-push: the URL/URL of the repository which Mercurial will try to upload your changes to when you run

   hg push

   . This option defaults to 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. 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 I already have a great Kerberos+publickey authentication based ssh server. So I instead push to the URL ssh://ohnopublishing.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 = https://ohnopublishing.net/hg/makeldif
default-push = ssh://ohnopublishing.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. I have, in fact, set up some repos on my server which pull other HTTPS and push against /home/hg/repos/makeldif which is a local directory, even though the HTTPS method is probably slower and more inefficient :-).