• Choose a category
• All
• Classic-Fiction

If you specify a -u option to the hg commit command on the command line, followed by a username, this is always given the highest precedence.

If you have set the HGUSER environment variable, this is checked next.

If you create a file in your home directory called .hgrc with a username entry, that will be used next. To see what the contents of this file should look like, refer to Creating a Mercurial configuration file.

If you have set the EMAIL environment variable, this will be used next.

Mercurial will query your system to find out your local user-name and host-name, and construct a username from these components. Since this often results in a username that is not very useful, it will print a warning if it has to do this.

If all of these mechanisms fail, Mercurial will fail, printing an error message. In this case, it will not let you commit until you set up a username.

You should think of the HGUSER environment variable and the -u option to the hg commit command as ways to override Mercurial’s default selection of username. For normal use, the simplest and most robust way to set a username for yourself is by creating a .hgrc file; see below for details.

Creating a Mercurial configuration file

To set a username, use your favorite editor to create a file called .hgrc in your home directory. Mercurial will use this file to look up your personalized configuration settings. The initial contents of your .hgrc should look like this:

# This is a Mercurial configuration file.

[ui]

username = Firstname Lastname

* * *

Home directory on Windows

When we refer to your home directory, on an English language installation of Windows this will usually be a folder named after your user-name in C:\Documents and Settings. You can find out the exact name of your home directory by opening a command prompt window and running the following command:

C:\> echo %UserProfile%

* * *

The [ui] line begins a section of the config file, so you can read the “username = ...” line as meaning “set the value of the username item in the ui section.” A section continues until a new section begins, or the end of the file. Mercurial ignores empty lines and treats any text from # to the end of a line as a comment.

Choosing a username

You can use any text you like as the value of the username config item, since this information is for reading by other people, but will not be interpreted by Mercurial. The convention that most people follow is to use their name and email address, as in the example above.

* * *

Note

Mercurial’s built-in web server obfuscates email addresses, to make it more difficult for the email harvesting tools that spammers use. This reduces the likelihood that you’ll start receiving more junk email if you publish a Mercurial repository on the Web.

* * *

Writing a Commit Message

When we commit a change, Mercurial drops us into a text editor to enter a message that will describe the modifications we’ve made in this changeset. This is called the commit message. It will be a record for readers of what we did and why, and it will be printed by hg log after we’ve finished committing:

$ hg commit

The editor that the hg commit command drops us into will contain an empty line or two, followed by a number of lines starting with HG:.

This is where I type my commit comment.

HG: Enter commit message. Lines beginning with 'HG:' are removed.

HG: --

HG: user: Bryan O'Sullivan

HG: branch 'default'

HG: changed hello.c

Mercurial ignores the lines that start with HG:; it uses them only to tell us which files it’s recording changes to. Modifying or deleting these lines has no effect.

Writing a Good Commit Message

Since hg log only prints the first line of a commit message by default, it’s best to write a commit message whose first line stands alone. Here’s a real example of a commit message that doesn’t follow this guideline, and hence