Mercurial

Client

http://hginit.com/

The command for Mercurial is hg.

Create a repository

Suppose you want to set up version control for the my_code directory.

cd my_code
hg init    # creates .hg directory
hg add     # adds everything from the current directory
hg commit  # has you enter a text description, then creates a first snapshot of the directory

Ignoring files

Manually create a file called .hgignore at the top level of your repository and add patterns that mercurial should ignore:

# use glob syntax.
syntax: glob
log/*  # ignore these directories in rails
tmp/*
*~     # ignore emacs backup files
*.bak  # ignore other backup files

Commit, Revert, Backout, Tag, Log

hg commit                  # has you enter a text description in a text editor, then creates a snapshot of the directory
hg commit -m "my comment"  # commit with this comment
hg revert --all            # reverts everything back to the last commit
hg rollback                # rolls back to the commit before last
hg backout -r 2            # undo just changeset number 2 
hg tag Version-1.0         # add a tag to the current changeset
hg log                     # shows a list of all commits

Status, Diff, Remove, Add

> cp a.txt b.txt
> emacs a.txt
> rm favicon.ico
> hg status
M a.txt                   # Modified
? b.txt                   # "?" means mercurial doesn't know anything about this file yet
! favicon.ico             # "!" means missing
>
> hg diff a.txt           # show differences between last snapshot and current version
> hg add                  # add all new files to repository
> hg remove favicon.ico   # really remove this file
> hg status
M a.txt
A b.txt                   # Added
R favicon.ico             # Removed

You need to clear up all the ?s and !s in order to commit.

Cat, Diff, Update

hg cat a.txt            # print current version of a.txt
hg cat -r 0 a.txt       # print version 0 of a.txt
hg diff -r 0:1 a.txt    # show differences between versions 0 and 1 of a.txt
hg update -r 0          # revert to version 0 of the repository
hg update               # revert to the latest version of the repository

Working with a server

hg clone http://my_server:8000/ my_copy_of_the_code  # name the directory as you like
... commit some changes ...
hg push                               # upload latest committed version to the server
... commit more changes ...
hg outgoing            # show differences between my current version and the server's

Push will fail if conflicting changes have been uploaded to the server in the meantime. If this happens, you need to merge the updates into your version:

hg incoming           # show differences between my current version and the server's
hg pull               # pull down more recent changes from the server
hg merge              # merge my version with the latest changes from the server
hg commit -m "merge"  # commit the merge
hg push               # upload

Pull does not automatically update the files in your directory to the latest version, it just downloads the latest changes. Use parent to see what version number you're currently working with:

hg parent             # show the changeset that’s in the working directory
hg heads              # show any changesets that are at the head of the repository

Workflow:

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

Experimenting

hg clone my_code my_code_experiment    # make a hard-linked duplicate directory
hg push                                # push experimental changes back into original directory

Stable and dev repositories

Clone my_code-stable to my_code-dev. Fix bugs in the stable repository, and add features in the dev repository. Regularly pull down bug fixes from stable to dev and merge them to stay current. When the new features are ready, push them back to stable.

Troubleshooting

When you first create your repository, add everything to it, and then try to commit, you get this error:

> hg commit -m "first commit"
error:  abort: no username supplied (see "hg help config") 

You must create a .hgrc file in your home directory and add something like this to it:

[ui]
username = Your Name <your@mail>

Server

Quick and dirty web server:

mkdir my_code
cd my_code
hg init
hg serve   # now accessible from http://my_server:8000/