From NoskeWiki
Jump to navigation Jump to search


Mercurial is a free, distributed source control management tool. It is mainly implemented using the Python programming language and supported on Windows, Mac OS X and Unix-like systems, including FreeBSD and Linux. I was introduced to Mercurial in 2011 and slowly figuring it out. So far I'm not sure I prefer it over CSV... the learning curve seems steeper but it does appear more powerful and has a neat ability to "merge" files that may have been edited in different places.


Installing Mercurial is pretty straightforward from Download the relevant package then restart your terminal window.

List of Commands

All of Mercurial's operations are invoked as keyword options to its driver program hg, a reference to the chemical symbol of the element mercury. If you type hg all the "basic commands" are listed. These are:

  • add ......... add the specified files on the next commit
  • annotate ......... show changeset information by line for each file
  • clone ......... make a copy of an existing repository
  • commit ......... commit the specified files or all outstanding changes
  • diff ......... diff repository (or selected files)
  • export ......... dump the header and diffs for one or more changesets
  • forget ......... forget the specified files on the next commit
  • init ......... create a new repository in the given directory
  • log ......... show revision history of entire repository or files
  • merge ......... merge working directory with another revision
  • pull ......... pull changes from the specified source
  • push ......... push changes to the specified destination
  • remove ......... remove the specified files on the next commit
  • serve ......... start stand-alone webserver
  • status ......... show changed files in the working directory
  • summary ......... summarize working directory state
  • update ......... update working directory (or switch revisions)
  • view ......... start interactive history viewer

The commands I have used and (mostly) understand are:

Command Description
hg clone ssh:// (DEST) to make a copy of an existing repository to the (DEST) directory you specify.
hg incoming see what changes would be made if you ran "pull", and add "-v" on the end to see what files have been changed. Use "hg outgoing" to see what changes of yours will be made.
hg status tells you what differs between your current files and your repository, where '$' means unsure 'A' for add and so on.
hg pull -u pull and updates, which is almost always what you want to do.
hg add [FILENAME] adds a file, but requires you to run "commit" and then "push" to actual save and then upload. Be warned that if you add a directory it will add all files in that directory (eg: hg add toolsfolder/) and you'd have to run "remove" on the ones you don't want or add them to an ignore list. It's easier to just add files individually (eg: hg add toolsfolder/file.c) and any directories will be created on other people's machines as necessary.
hg commit -m "comment" [FILENAME] after adding a file... or if you just want to upload changes, you must run commit. The -m tag is helpful - without it it will go to a default editor and let you type in a multi-line comment, but I find this annoying.. and if the default editor is vim you have to type [esc] then enter ":wq" to save an exit.
hg fetch does a "merge" and updating all at once, unless there are conflicts. It's a good idea to run this just before you push.
hg push merges the changes in your repository into the master.
hg help gives a list of commands.
hg help command gives terse help for one command.

Resolving Merge Problems

When you run hg merge or hg fetch, you will occasionally see merge issues. Ideally you will have a program like "kDiff" setup and installed so that if file conflict it will immediately show and help you resolve the differences. Instructions on setting up kDiff are here, but here we'll assume you don't have kDiff installed. If I come into problems with fetch or merge some you can resolve it by running these steps:

Step 1: Identify and problematic files and view differences:

  • # hg status
    • ... to work out what's "M" (modified), and can look at these files and make backups of any you are worried about
  • # hg diff FILENAME.cpp
    • ... will shows differences as + and -'s a the "<<<<<" tags are the important ones that merge cannot handle

Step 2: Fix the files:

  • If you are happy to use remote changes you can run this fairly safe command:
    • # hg revert FILENAME.cpp --> will leave you with a .orig file...
  • Otherwise: use any editor to change your file as desired.

Step 3: Mark changes as resolved and update:

  • # hg resolve -l
    • ... will list files that need resolving
  • # hg resolve -m FILENAME.cpp
    • ... tells mercurial that you've taken care of merge yourself
  • # hg commit -m "comment" FILENAME
  • # hg fetch
    • ... and now should be up to date, and ready to push or whatever....

Here's a summary of the important commands:

hg status
hg diff X
hg resolve -m X
hg commit -m "comment" X

Setting up your username (.hgrc)

To make any changes you'll need a username... and to set this username "permanently" you'll need to create a ".hgrc" file in your home directory. To create this file type

pico ~/.hgrc

And then add the following:

username = First Last <>

One annoying feature of Mercurial is how frequently you maybe prompted for a password, which I believe can be fixed by adding:

repo.prefix = https://server/repo_path
repo.username = username
repo.password = password