hg - the simple guide

just a simple guide for getting started with hg. no deep shit ;)


by Han Xiaogang
credits to Roger Dudler
please report issues on github


Download hg for OSX/Windows/Linux

create a new repository

create a new directory, open it and perform a
hg init
to create a new hg repository.

checkout a repository

create a working copy of a local repository by running the command
hg clone /path/to/repository
when using a remote server, your command will be
hg clone username@host:/path/to/repository


Unlike git, which maintains three "trees" in your local repository: Working Directory, Index, and HEAD, Hg hides such it and handles it automatically so that the user don't need to deal with it.

add & commit

You can propose changes (add it to the Index) using
hg add <filename>
hg add
This is the first step in the basic hg workflow. To actually commit these changes use
hg commit -m "Commit message"
Now the file is committed to the HEAD, but not in your remote repository yet.

pushing changes

Your changes are now in the HEAD of your local working copy. To send those changes to your remote repository, execute
hg push
hg push -b branch_name
Change master to whatever branch you want to push your changes to.

If you have not cloned an existing repository and want to connect your repository to a remote server, you need to add it in .hg/hgrc
default = <server>
Now you are able to push your changes to the selected remote server


Branches are used to develop features isolated from each other. The master branch is the "default" branch when you create a repository. Use other branches for development and merge them back to the master branch upon completion.

create a new branch named "feature_x" and switch to it using
hg branch feature_x
hg commit -m "start feature_x branch"
switch back to default
hg update default
and close the branch
hg update feature_x
hg commit -m 'close feature_x' --close-branch
a branch is not available to others unless you push the branch to your remote repository
hg push -b <branch>

update & merge

to update your local repository to the newest commit, execute
hg pull
in your working directory to fetch remote changes.
and merge if necessary
hg merge
to merge another branch into your active branch (e.g. master), use
hg merge <branch>
in both cases hg tries to auto-merge changes. Unfortunately, this is not always possible and results in conflicts. You are responsible to merge those conflicts manually by editing the files shown by hg. After changing, you need to commit the results of the merge with
hg commit -m "Merge message"
before merging changes, you can also preview them by using
hg diff -r <source_branch>:<target_branch>


it's recommended to create tags for software releases. this is a known concept, which also exists in SVN. You can create a new tag named 1.0.0 by executing
hg tag -r 1b2e1d63ff 1.0.0
hg tag 1.0.0
the 1b2e1d63ff stands for the first 10 characters of the commit id you want to reference with your tag. You can get the commit id by looking at the...


in its simplest form, you can study repository history using.. hg log
You can add a lot of parameters to make the log look like what you want. To see only the commits of a certain author:
hg log -u bob
These are just a few of the possible parameters you can use. For more, see hg help log

replace local changes

In case you did something wrong (which for sure never happens ;) you can replace local changes using the command
hg update -C
this replaces the changes in your working tree with the last content in HEAD. Changes already added to the index, as well as new files, will be kept.

If you instead want to drop all your local changes and commits, fetch the latest history from the server and point your local master branch at it like this
hg pull
hg update -r default -C

links & resources

graphical clients


get help