Development:Helpful Mercurial Commands

Mercurial is modern, powerful VCS; it also makes it very easy for you to shoot yourself in the foot. Here are some Hg commands to help you harness the former and prevent (or recover from) the latter.

For more information about any of these commands, use hg --help $cmdname.

rename (mv)

To move or rename a file managed by Hg, simply hg mv $source $destination, and Hg will move the contents of the file to the new name/location, mark the old name/location for deletion, and mark the new name/location for addition.

rollback

To roll back the last transaction (commit, import, pull, push to a local repository you control, unbundle), simply hg rollback.

Mercurial help warns that there is only one level of rollback, rollback is not undoable, and that rollback reverts all repository changes since the last transaction (but it does not affect your working copy). rollback cannot undo changes you’ve pushed to a remote repository, e.g. to hg.mozilla.org/camino.

For example, you’ve committed but realize you’re missing a file (or committed all local changes in your working directory by accident); hg rollback removes the commit (but does not undo the actual changes in your working copy), so you can commit again with the right set of files.

revert

If you’ve made a mistake with a file, perhaps accidentally deleting it or mangling it beyond all recognition, hg revert will get you out of the mess as long as you haven’t committed. Revert will restore your entire working copy (or specific files in your working copy) to the state of the local repository (i.e., to what is stored in the hidden .hg directory, not to the state of the remote repository). This restores the contents of files (saving the current state in .orig files) and undoes any adds, removes, copies, and renames.

For example, you accidentally deleted Camino.xcodeproj/project.pbxproj; hg revert Camino.xcodeproj/project.pbxproj will restore the project to the state it was in at the time of your last pull from hg.mozilla.org/camino.

In this second example, you attempted to apply a massive whitespace patch that touched 90% of the code and manually fix up conflicts, but the result failed to build. Here, hg revert --all will make your working copy a mirror of the repo state at the time of your last pull from hg.mozilla.org/camino. (Unfortunately, it also reverts local changes you had made to year.txt before trying to apply the patch; you can recover those local changes from year.txt.orig after running hg revert --all.

outgoing

hg outgoing will tell you what changesets (commits) you are about to push to the official repository with hg push.

Mercurial Queues

Mercurial Queues (mq for short) are apparently a powerful patchset management tool loved by Mozilla developers, provided by the (off-by-default) mq extension to Mercurial. Unfortunately, the documentation assumes you already understand them.

philor offers this explanation:

[3:47pm] philor: irc-length explanation of mq: "say |hg qnew foo|, make a bunch of 
                 changes, |hg qref|, |hg qpop|, |hg qnew bar| and you are working on the 
                 patch for bar in a clean untouched repo, with all of foo saved and ready 
                 to reapply"

[3:48pm] ardissone: so it juggles patches in and out?

[3:48pm] philor: right

[3:50pm] ardissone: it's rare that I do that normally, but I have been doing it a lot recently 

[3:50pm] philor: very handy for chickens, too, especially with the qimport extension

[3:51pm] philor: so that |hg qimport bz:12345| imports the patch from bug 12345, but you can 
                 then shuffle order and address review comments and change the commit message 
                 and change the user and whatnot at leisure

[3:51pm] thebot: philor: Bug https://bugzilla.mozilla.org/show_bug.cgi?id=12345 nor, P1, M11, 
                 jefft, VERI FIXED, [DOGFOOD] Unable to Forward a message received as an Inline 
                 page or an attachment

[3:57pm] philor: though reading https://developer.mozilla.org/en/Mercurial_Queues with the 
                 stale eyes of having used it for going on two years, wow, we really need a 
                 Gentle Introduction

[3:57pm] ardissone: yeah

[3:57pm] ardissone: The Moz hg docs suck rocks

[3:57pm] philor: but at least when you compare them to hg's docs, they start looking good

[3:58pm] ardissone: partly, apparently, because jorendorff explicitly wanted them to be inaccessible 

[3:58pm] ardissone: yeah 

[3:58pm] ardissone: i read some stuff from joelonsoftware and someone else

[4:00pm] ardissone: which were generally useful to helping me get acquainted to the differences 
                    between hg and cvs, but not so much for the mozilla-specific stuff (or mq)