First time users

  1. is an excellent tutorial If you've never worked with a version control system before, you might want to read that small introduction to VCS.
  2. How to setup tortoiseHG shows you the first steps on how to get going

1st checkout

anonymous HTTP

hg clone<project> [<alias>]

authenticated SSH

hg clone ssh://<project> [<alias>]


update workcopy

hg update [<version>] (head if none)

synchronize Repository

from server

hg pull [-u] [<url>] 

(the same url as for clone) Use option -u in order to update the repository at the same time.

to server

hg push [<url>] (url from .hg/hgrc)

(with ssh)

If you encounter the message push creates new remote heads! (did you forget to merge? use push -f to force) you usually want to pull from the repository and merge your changes with the new changes you pulled.

It isn't an "error" message; it's a totally normal situation. That message is saying "hey, other people pushed new work to that repository while you were doing your work, you should probably integrate theirs into your so they don't have to integrate yours into theirs?"

So first do a:

hg pull

and then a:
hg merge

Use push -f only when you know what you do and you know that you want to push an additional head.

Always know where you are

If you use bash shell, you can modify your command prompt to always give feedback on the repository you are in as well as the current status of the working directory. Amend your ~/.bashrc

hg_ps1() {
    if $(hg st > /dev/null 2>&1); then 
        hg log -r. --template=' {branch}-r{rev}{if(tags," ({tags})")}{if(bookmarks," ({bookmarks})")} '
hg_ps2() {
    if $(hg st > /dev/null 2>&1); then
        basename $(hg root)

export PS1='\u@\h\e[32m $(hg_ps2)\e[31m$(hg_ps1)\e[39m\w $ '

And your command prompt will always show the project name as well as the currently checked-out revision:

planetmaker@aeolus nml default-r2260 (tip) ~/ottd/grfdev/nml $ hg up 0.2
182 files updated, 0 files merged, 38 files removed, 0 files unresolved
planetmaker@aeolus nml 0.2-r2128 ~/ottd/grfdev/nml $ 

h2. Advanced usages

  • Using evolve to prepare a small feature

Mercurial references - Basic Mercurial - The Definitive Guide - Hg Init: a Mercurial tutorial