Recently I’ve been working with a third party component vendor to resolve a defect. They requested that I create a sample project illustrating the issue and send it to them as a zip archive. Building the project was easy but I didn’t want to send all of the extra stuff that goes along with it. In other words, I wanted a snapshot of the current revision but without the source control bindings.  I knew how to do this with Subversion but how did Mercurial handle it?

In Subversion the command to get a clean, unbound copy of the repository contents is svn export. I’ve used this command a few times mostly for archival purposes.  Mercurial offers similar functionality through the archive command.

In its most basic form hg archive is nearly identical to svn export. By default Mercurial will simply populate a destination folder with unversioned copies of what’s in the repository. For instance, if I want to create a snapshot of the repository in a folder named Archive I can run the following command:

hg archive Archive

The resulting folder would contain everything I need to include in the zip that the vendor requested.  Although the folder would be sufficient it’s not optimal.  What if I want to archive an older revision?  What if I want to exclude certain files from the archive?  Like its Subversion counterpart hg archive gives us some control over the archival process.

Specify a revision:

hg archive -r 55 Archive

Exclude repository artifacts:

hg archive -X ".hg*" Archive

The thing that really excites me about the archive command though is a major convenience it provides. So far we’ve only looked at filling a folder with a copy of the repository. I could create a new zip file from the archive folder but wouldn’t it be nice to archive straight to a zip (or other archival format) instead?

hg archive has built-in support for writing several different archival types beyond simply archiving the files to a folder. In my case I needed to send a zip file to the vendor so I could easily generate it by running:

hg archive -X ".hg*" Archive.zip

The command will automatically detect the desired format based on the target file’s extension but it can also be overridden with the <kbd>-t</kbd> option. The supported types are:

• tar (uncompressed)
• tbz2 (compressed with bzip2)
• tgz (compressed with gzip)
• uzip (uncompressed)
• zip (compressed with deflate)

The ability to archive straight to a convenient archival format is a great time saver. I highly recommend taking a look at the documentation (particularly hg -v help archive) for the command to see what else it provides.