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

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?

Solution 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.

Solution 2:

Instead of doing a partial clone, you can use the Convert Extension to split your repo into more than one repo by sub repository.

Specifically, see the section, Converting from Mercurial:

It's also useful to filter Mercurial repositories to get subsets of an existing one. For example to transform a subdirectory subfoo of a repository foo into a repository with its own life (while keeping its full history), do the following:

$ echo include subfoo > /tmp/myfilemap
$ echo rename subfoo . >> /tmp/myfilemap
$ hg convert --filemap /tmp/myfilemap /path/to/repo/foo /tmp/mysubfoo-repo

Solution 3:

I've stumbled accross this issue and found one way to do it: Using symlinks (Linux only unfortunately)

For example, if you only need /project in the repository, on your computer clone the repo in another folder, then use ln -s /repo/location/ project. Mercurial will handle it