Share this page

Learn X in Y minutes

Where X=Mercurial

Mercurial is a free, distributed source control management tool. It offers you the power to efficiently handle projects of any size while using an intuitive interface. It is easy to use and hard to break, making it ideal for anyone working with versioned files.

Versioning Concepts

What is version control?

Version control is a system that keeps track fo changes to a set of file(s) and/or directorie(s) over time.

Why use Mercurial?


Term Definition
Repository A repository is a collection of revisions
hgrc A configuration file which stores the defaults for a repository.
revision A committed changeset: has a REV number
changeset Set of changes saved as diffs
diff Changes between file(s)
tag A named named revision
parent(s) Immediate ancestor(s) of a revision
branch A child of a revision
head A head is a changeset with no child changesets
merge The process of merging two HEADS
tip The latest revision in any branch
patch All of the diffs between two revisions
bundle Patch with permisĀ­sions and rename support



Create a new repository in the given directory, the settings and stored information are in a directory named .hg.

$ hg init


Will give you access to a very detailed description of each command.

# Quickly check what commands are available
$ hg help

# Get help on a specific command
# hg help <command>
$ hg help add
$ hg help commit
$ hg help init


Show the differences between what is on disk and what is committed to the current branch or tag.

# Will display the status of files
$ hg status

# Get help on the status subcommand
$ hg help status


Will add the specified files to the repository on the next commit.

# Add a file in the current directory
$ hg add filename.rb

# Add a file in a sub directory
$ hg add foo/bar/filename.rb

# Add files by pattern
$ hg add *.rb


Set or show the current branch name.

Branch names are permanent and global. Use ‘hg bookmark’ to create a light-weight bookmark instead. See ‘hg help glossary’ for more information about named branches and bookmarks.

# With no argument it shows the current branch name
$ hg branch

# With a name argument it will change the current branch.
$ hg branch new_branch
marked working directory as branch new_branch
(branches are permanent and global, did you want a bookmark?)


Add one or more tags for the current or given revision.

Tags are used to name particular revisions of the repository and are very useful to compare different revisions, to go back to significant earlier versions or to mark branch points as releases, etc. Changing an existing tag is normally disallowed; use -f/–force to override.

# List tags
$ hg tags
tip                                2:efc8222cd1fb
v1.0                               0:37e9b57123b3

# Create a new tag on the current revision
$ hg tag v1.1

# Create a tag on a specific revision
$ hg tag -r efc8222cd1fb v1.1.1


Create a copy of an existing repository in a new directory.

If no destination directory name is specified, it defaults to the basename of the source.

# Clone a remote repo to a local directory
$ hg clone

# Clone a local repo to a remote server
$ hg clone . ssh://[email protected]/newrepo

# Clone a local repo to a local repo
$ hg clone . /tmp/some_backup_dir

commit / ci

Commit changes to the given files into the repository.

# Commit with a message
$ hg commit -m 'This is a commit message'

# Commit all added / removed files in the current tree
$ hg commit -A 'Adding and removing all existing files in the tree'

# amend the parent of the working directory with a new commit that contains the
# changes in the parent in addition to those currently reported by 'hg status',
$ hg commit --amend -m "Correct message"


Show differences between revisions for the specified files using the unified diff format.

# Show the diff between the current directory and a previous revision
$ hg diff -r 10

# Show the diff between two previous revisions
$ hg diff -r 30 -r 20


Search revision history for a pattern in specified files.

# Search files for a specific phrase
$ hg grep "TODO:"

log / history

Show revision history of entire repository or files. If no revision range is specified, the default is “tip:0” unless –follow is set, in which case the working directory parent is used as the starting revision.

# Show the history of the entire repository
$ hg log

# Show the history of a single file
$ hg log myfile.rb

# Show the revision changes as an ASCII art DAG with the most recent changeset
# at the top.
$ hg log -G


Merge another revision into working directory.

# Merge changesets to local repository
$ hg merge

# Merge from a named branch or revision into the current local branch
$ hg merge branchname_or_revision

# After successful merge, commit the changes
hg commit

move / mv / rename

Rename files; equivalent of copy + remove. Mark dest as copies of sources; mark sources for deletion. If dest is a directory, copies are put in that directory. If dest is a file, there can only be one source.

# Rename a single file
$ hg mv foo.txt bar.txt

# Rename a directory
$ hg mv some_directory new_directory


Pull changes from a remote repository to a local one.

# List remote paths
$ hg paths
remote1 = http://path/to/remote1
remote2 = http://path/to/remote2

# Pull from remote 1
$ hg pull remote1

# Pull from remote 2
$ hg pull remote2


Push changesets from the local repository to the specified destination.

# List remote paths
$ hg paths
remote1 = http://path/to/remote1
remote2 = http://path/to/remote2

# Pull from remote 1
$ hg push remote1

# Pull from remote 2
$ hg push remote2


Move changeset (and descendants) to a different branch.

Rebase uses repeated merging to graft changesets from one part of history (the source) onto another (the destination). This can be useful for linearizing local changes relative to a master development tree.

# Put the commits into draft status
# This will draft all subsequent commits on the relevant branch
$ hg phase --draft --force -r 1206

# Rebase from from revision 102 over revision 208
$ hg rebase -s 102 -d 208


Restore files to their checkout state. With no revision specified, revert the specified files or directories to the contents they had in the parent of the working directory. This restores the contents of files to an unmodified state and unschedules adds, removes, copies, and renames. If the working directory has two parents, you must explicitly specify a revision.

# Reset a specific file to its checked out state
$ hg revert oops_i_did_it_again.txt

# Revert a specific file to its checked out state without leaving a .orig file
# around
$ hg revert -C oops_i_did_it_again.txt

# Revert all changes
$ hg revert -a

rm / remove

Remove the specified files on the next commit.

# Remove a specific file
$ hg remove go_away.txt

# Remove a group of files by pattern
$ hg remove *.txt

Further information

Got a suggestion? A correction, perhaps? Open an Issue on the GitHub Repo, or make a pull request yourself!

Originally contributed by Will L. Fife, and updated by 4 contributors.