Post Pic

Customising your mercurial.ini configuration file to get the most out your experience

I am doing an increasing amount of collaborative work at the moment. During the course of these collaborations I have been giving access to some of my Mercurial repositories on BitBucket  to other developers and noticed that simple things like a consistent username have not been configured in their environments. This is resulting in each commit to my repositories often having a different username and meaning I have to keep mapping alias after alias to the BitBucket user accounts so my repo’s look nice and tidy with peoples avatars all displaying correctly (because I’m anal like that!).

Having spoken to one of the other developers about updating his mercurial.ini file with a static username and email address I found he was blissfully unaware of the feature as I expect are many others and hence my blog post.

You should find your Mercurial configuration file in %USERPROFILE%mercurial.ini. If your’s is not there you can either create it or refer to the Configuration files for Mercurial documentation.

See below for an extract of my mercurial.ini configuration file with a breakdown below of the purpose for each configuration setting:

[ui]
username = Simon Dingley <simon@prolificnotion.co.uk>
verbose = True
editor = "C:Program Files (x86)Notepad++notepad++.exe" -multiInst -nosession
merge = tortoisemerge
ssh = "TortoisePlink.exe" -ssh -2 -batch -C

[paths]
ucpp = ssh://hg@bitbucket.org/ProNotion/ucommerce-payment-providers
umbraco = https://hg.codeplex.com/umbraco

[extensions]
color =
progress =
convert =
fetch =

[tortoisehg]
vdiff = tortoisemerge

[ui]

username

Identifies the user committing the changeset. Typically a person’s name and email address, e.g. Simon Dingley <simon@example.com>. Default is often username@hostname and one of the reasons for this blog post.

verbose

Display more detailed output. Default is False. I find this useful to know what is going on in the background.

editor

This is the application to use for editing comments relating to your commits. As you can see, my preferred choice is Notepad++ but could really be any text editor of your choice.

merge

This is your tool of choice for resolving merge conflicts, my personal preference is still with tortoisemerge which I am familiar with from my Subversion days. I’ve tried a few alternatives but this is the one that works for me so I’ve stuck with it.

ssh

This is a relatively new addition to my configuration file and provides mercurial with the command to execute for any SSH connections. Depending on interest in this I may at a later date do another post on setting up SSH with mercurial to save the hassle of entering repository login details all of the time.

[paths]

This section of the configuration file allows you to supply shorter friendly names for your repositories so you don’t need to enter the full repository address each time you want to interact with it by means of pushing or pulling changesets. So taking my example below I can very quickly pull from the Umbraco repository by typing the following into my chosen command prompt:

hg pull umbraco

[extensions]

This section defines any extensions you wish to use to add additional features to your mercurial experience. Some Mercurial extensions are available right out of the box. TO enable an extension that already comes with Mercurial you simply need to add the name of the extension followed by the = sign in order to load the extension with Mercurial it’s really that easy. If you want to load any other extensions you simply supply the path after the = sign.

Here is a quick overview of the extensions I currently have enabled…

color

This basically provides colouring of the output if you do a diff in your command window (which I don’t often as I find it far too hard to read and instead use the tortoisehg GUI. Read more about the Mercurial Color extension.

progress

This is one of the first extensions I enabled to get some visual feedback on the progress of push/pull commands which otherwise would cause the process to look like it is doing nothing – again this is just visual fluff! Read more about the Mercurial Progress extension.

convert

This is one I used mostly in my early days of moving from SubVersion to Mercurial and allows you to convert repositories from other source control repositories to Mercurial. I still use this on occassion. Read more about the Mercurial Convert extension.

fetch

I don’t use this as often as I should but it’s basically a productivity enhancement and saves writing a couple of commands by combining pull, merge and update into a single command. Read more about the Mercurial Fetch extension.

Other bundled extensions

For a full list of bundled extensions you can Extensions bundled with Mercurial entry on the Mercurial wiki.

[tortoisehg]

vdiff

This is a configuration section added by the tortoisehg GUI and simply defines my preferred visual diff editor. I’m actually not sure why it is redefined instead of using the tool already defined in my [ui] section.

So that’s a wrap on this post however in a related note you may wish to read my other post ‘Console2 – My new and improved command prompt for Windows‘ which I use for entering all of my Mercurial commands.

Any feedback or requests for additions to this post would be useful and I will look to keep it up to date as I build up my configuration file further in the future.

Umbraco Certified Developer
SagePay Approved Partner
Creative Market