• Choose a category
• All
• Classic-Fiction

If you would like to add a diffstat-format summary to each patch, and one to the introductory message, use the hg -d option. The diffstat command displays a table containing the name of each file patched, the number of lines affected, and a histogram showing how much each file is modified. This gives readers a qualitative glance at how complex a patch is.

Appendix A. Migrating to Mercurial

A common way to test the waters with a new revision control tool is to experiment with switching over an existing project, rather than starting a new project from scratch.

In this appendix, we discuss how to import a project’s history into Mercurial, and what to look out for if you are used to a different revision control system.

Importing History from Another System

Mercurial ships with an extension named convert, which can import project history from most popular revision control systems. At the time this book was written, Mercurial could import history from the following systems:

Subversion

CVS

Git

Darcs

Bazaar

Monotone

GNU Arch

Mercurial

(To see why Mercurial itself is supported as a source, see Tidying Up the Tree.)

You can enable the extension in the usual way, by editing your ~/.hgrc file.

[extensions]

convert =

This will make an easy-to-use hg convert command available. For instance, the following command will import the Subversion history for the Nose unit testing framework into Mercurial.

$ hg convert http://python-nose.googlecode.com/svn/trunk

The convert extension operates incrementally. In other words, after you have run hg convert once, running it again will import any new revisions committed after the first run began. Incremental conversion will only work if you run hg convert in the same Mercurial repository that you originally used, because the convert extension saves some private metadata in a non-revision controlled file named .hg/shamap inside the target repository.

When you want to start making changes using Mercurial, it’s best to clone the tree in which you are doing your conversions, and leave the original tree for future incremental conversions. This is the safest way to let you pull and merge future commits from the source revision control system into your newly active Mercurial project.

Converting Multiple Branches

The hg convert command given above converts only the history of the trunk branch of the Subversion repository. If we instead use the URL http://python-nose.googlecode.com/svn, Mercurial will automatically detect the trunk, tags, and branches layout that Subversion projects usually use, and it will import each as a separate Mercurial branch.

By default, each Subversion branch imported into Mercurial is given a branch name. After the conversion completes, you can get a list of the active branch names in the Mercurial repository using hg branches -a. If you would prefer to import the Subversion branches without names, pass the --config convert.hg.usebranchnames=false option to hg convert.

Once you have converted your tree, if you want to follow the usual Mercurial practice of working in a tree that contains a single branch, you can clone that single branch using hg clone -r mybranchname.

Mapping Usernames

Some revision control tools save only short usernames with commits, and these can be difficult to interpret. The norm with Mercurial is to save a committer’s name and email address, which is much more useful for talking to them after the fact.

If you are converting a tree from a revision control system that uses short names, you can map those names to longer equivalents by passing the --authors option to hg convert. This option accepts a filename that should contain entries of the following form.

arist = Aristotle

soc = Socrates

Whenever convert encounters a commit with the username arist in the source repository, it will use the name Aristotle