Mercurial Tips

While most of the world seems to be using git for version control, Mozilla continues to use Mercurial (hg) to manage the Firefox source code. As a git and GitHub lover, it took me a while to get used to Mercurial. I don't consider myself a hg expert but I know enough to complete 99% of the tasks required...which is probably about how much I know about git. Just enough to be dangerous, I guess.

This post will cover some of the tasks I frequently complete with Mercurial.

Create a Commit with Message

You can add -m to add the message from command line instead of entering VIM or your desired editor:

hg commit -m "Bug #### - This is the commit message"

This is the same format as git.

Import a Patch

Mercurial lets you import patches from both local files and URLs:

# From local file
hg import /path/to/code.patch

# From URL
hg import https://bugzilla.mozilla.org/attachment.cgi?id=32894.patch

Get Latest Public Commits

The commits you make locally are in "draft" status; "public" commits are commits in the official repository. You can pull new commits from the main repository with pull:

# Pull down new commits and check out latest
hg pull && hg update --clean

# Only checkout latest
hg checkout "last(public())"

Delete All Untracked Files

Mercurial generates .orig files when you revert changed files, just in case you need those changes in the future. When you want to get rid of untracked files, you can use purge:

hg purge

Rebase a Commit

The rebase option lets you provide a variety of options:

# Provide a source and destination revision (123 onto 200)
# hg rebase -s <REV> -d <REV>
hg rebase -s 12345 -d 12400

# Rebase the currently checked out revision onto a destination
hg rebase -d 200

# Rebase onto the last public commit
hg rebase -s 12345 -d 'last(public())`

Delete a Commit

Sometimes you need to remove a commit:

# hg strip <REV>
hg strip 12345

Checkout a Commit that Contains a Search String

In the case that my patch gets reviewed and requires updates, I need to find the commit by the bug number which I provided in the commit message:

# Format: hg checkout "grep(SEARCH STRING)"
# Find the revision with message containing a search string
hg checkout "grep(Bug 1565318)"

Create and Delete Bookmarks

Bookmarks are the closest thing to git branches -- you can apply a text-based reference label to a commit:

# Create a bookmark
hg bookmark bug-12345

# Delete a bookmark -- doesn't delete commit
hg bookmark -d bug-12345

Change a Commit Author

Every once in a while I need to pull a patch from GitHub into my Mozilla Central repository for committing, but I don't want to steal credit for a contributor's brilliant patch.

hg commit -u "User Name <username@domain.com>" -m "The commit message"

Manage History

The histedit directive provides a listing of commits from a given parent and allows you to edit their commit messages, merge commits, drop commits, reorder commits, and more:

hg histedit

Truth be told, if you learn these commands, you'll be able to do mostly all you'll ever need to with Mercurial. I appreciate that Mercurial and git are incredibly powerful yet the basics are all 99% of developers need!

Feel free to ask questions in this post -- I'll add more commands as questions are asked!