Drop Shadow

Mercurial guidelines

We use Mercurial for version control. Version control allows us to easily see when changes were made and what those changes were. It also helps us to better coordinate multiple people working on the same project. It even lets us quickly back up to a previous version should the need arise.

You can use Mercurial on the command-line, or you can use a GUI front end such as Murky for Mac OS X.

  • Always look before you commit. Make sure that the changes you see are the changes you expect to see. If there are unexpected changes, find out why before you commit them. If you’ve left in some debug code, remove it.
  • Always pull before you commit. If someone else has made changes to unrelated files, it is easy to merge them before you commit the changes, but if you commit and then discover that someone else has pushed since the last time you pulled, you’ll end up having to commit their changes as well as yours as you merge the two commits.
  • Always pull before you start working. This ensures that you have the latest files.
  • Always read the messages that your Mercurial front-end displays. If you don’t understand them, take a screenshot.
  • Commit often! Break your updates into as small a unit as is reasonable; most major features can be broken into smaller features. Each commit should be one simple feature or one fixed bug. This will allow the diff view to show only a single new feature’s changes.


The command-line “hg” command will request a password whenever it needs one. Murky will not; you’ll need to install a keychain, such as the Mercurial keyring extension to store your passwords. Once installed, use the command line version once, and it will then store the password securely for future use.


The Mercurial tutorial in the sidebar is a very good, easy to follow guide to Mercurial and to version control. We also have a PDF handout for an occasional tutorial on the system documents page.