Compare to Subversion

  • Branching and merging
    • Branching causes problems in Subversion because Subversion doesn’t store enough information to make merging work.
      • Subversion always gives you this horrible dilemma. Either the repository is full of bugs because it includes new code that was just written, or new code that was just written is not in the repository.
    • In Mercurial, merging is painless and easy, and so branching is commonplace and harmless.
      • you can commit (hg com) without anyone else getting your changes. When you’ve got a bunch of changes that you like that are stable and all is well, you push them (hg push) to the main repository.
  • Changes vs. Versions
    • In Subversion, you might think, “bring my version up to date with the main version” or “go back to the previous version.”
    • In Mercurial, you think, “get me Jacob’s change set” or “let’s just forget that change set.”
  • Paradigm Shift
    • With distributed version control, the distributed part is actually not the most interesting part.
      • The interesting part is that these systems think in terms of changes, not in terms of versions.
    • Mercurial thinks in terms of “changesets” instead of “revisions” it can merge code much better than Subversion.
      • When you manage changes instead of managing versions, merging works better, and therefore, you can branch any time your organizational goals require it, because merging back will be a piece of cake.
  • Revision control
    • Subversion is basically revision control for files
    • but in Mercurial, revision control always applies to an entire directory—including all subdirectories.



  • working directory
  • repository
    • local repository
    • remote repository
  • changesets


  • for the Working Directory only
    • add
    • remove
    • status (st)
    • shelve — TortoiseHg only
      • remove selected changes from the working directory and place the changes in a patch file
    • unshelve — TortoiseHg only
      • reapply shelved changes to the working directory
    • branch
      • With one argument, set the working directory branch name
        • ensure that the next commit is “stamped” with the branch name.
        • changing the branch name counts as a change
      • With no argument, show the current branch name.
  • between the Working Directory and the Local Repository
    • commit (com, ci)
    • update (up, checkout, co)
      • Update the repository's working directory to the specified changeset.
      • If no changeset is specified, update to the tip of the current named branch.
    • revert
    • diff
    • merge — merge working directory with another revision
    • rollback — roll back the last transaction
    • parents — show the parents of the working directory or revision
    • backout — reverse effect of earlier changeset
  • for the Local Repository
    • init — create a new repository in the given directory
    • log — show revision history of entire repository or files
    • cat — output the current or given revision of files
    • serve — export the repository via HTTP
    • annotate — show changeset information by line for each file
    • paths — show aliases for remote repositories
    • heads — show current repository heads or show branch heads
    • tag — add one or more tags for the current or given revision
    • tags — list repository tags
    • branches — list branches
    • rebase — use repeated merging to graft changesets from one part of history (the source) onto another (the destination).
  • between the Local Repository and a Remote Repository
    • clone — make a copy of an existing repository
      • also update the Working Directory
    • push — push changes to the specified destination (remote repository)
    • pull — pull changes from the specified source (remote repository)
    • outgoing (out) — show changesets not found in the destination (remote repository)
      • list any changes in the current repository that aren’t in the central repository
    • incoming (in) — show new changesets found in source (remote repository)

Work Flow

When you’re working on a team, your workflow is going to look a lot like this:

  1. If you haven’t done so in a while, get the latest version that everyone else is working off of:
    • hg pull
    • hg up
  2. Make some changes
  3. Commit them (locally)
  4. Repeat steps 2-3 until you’ve got some nice code that you’re willing to inflict on everyone else
  5. When you’re ready to share:
    • hg pull to get everyone else’s changes (if there are any)
    • hg merge to merge them into yours
    • test! to make sure the merge didn’t screw anything up
    • hg commit (the merge)
    • hg push




  • Starting with the 1.0 release, Windows 2000 is no longer supported. The installer will refuse to install on Windows 2000. Minimum required version is Windows XP.


Split a repository in many

Add the following lines to your .hgrc or to enable the extension :


hg convert --authors=authors.txt --filemap=filemap.txt path/to/foo-bzr-branch foo-hg


john=John Smith <>
tom=Tom Johnson <>


include "."
exclude "doc"
include "doc/foo bar.txt"
include "doc/FAQ"
rename "doc/FAQ" "faq"
hg update
hg tag --remove tagname
hg bookmark -r default master


Suggested Readings

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License