How do I clone a sub-folder of a repository in Mercurial?

Question

I have a Mercurial repository containing a handful of related projects. I want to branch just one of these projects to work on it elsewhere.

Is cloning just part of a repository possible, and is that the right way to achieve this?

Answer 1

What you want is a narrow or partial clone, but this is unfortunately not yet supported.

If you already have a big repository and you realize that it would make sense to split it into several smaller repositories, then you can use the convert extension to do a Mercurial to Mercurial conversion. Note that this creates a new repository foo and you cannot push/pull between your-big-repo and foo.

The convert extension is not enabled by default so add the following to your repo's hgrc file or your mercurial.ini file:

[extensions] hgext.convert= 

Then create a map.txt file with

include "libs/foo" rename "libs/foo" . 

(note you can use forward slashes even on Windows) and run

$ hg convert --filemap map.txt your-big-repo foo 

That will make foo a repository with the full history of the libs/foo folder from your-big-repo.

If you want to delete all evidence of foo from your-big-repo you can make another conversion where you use exclude libs/foo to get rid of the directory.

When you have several repositories like that and you want to use them as a whole, then you should look at subrepositories. This feature lets you include other repositories in a checkout — similarly to how svn:externals work. Please follow the recommendations on that wiki page.