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?

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.

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

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

(Late 2016) Mainline Mercurial still doesn't package support for "narrow clones" but there are third party extensions that tackle the problem in different ways.

If you can cope with just a narrow checkout (aka "sparse checkout" or "partial checkout by file path") then Facebook's sparse.py extension from the hg-experimental repository (look inside the hgext3rd/ directory) may be workable. In this scenario, you still clone the full history (thus the .hg directory is no smaller) but your working directory only shows/acts on a subset of the full repository.

Alternatively Google have created a NarrowHG extension that does narrow cloning (aka "partial cloning by file path"). You will need to be in control of the server, the client and be willing to use experimental features but it really does restrict the clone's copied history in .hg to a subset of what was in the original repository.

(2019) The sparse extension was merged into Mercurial 4.3 as the experimental sparse extension. The NarrowHG extension was merged into Mercurial 4.6 as the hgext.narrow extension.

It is not possible, hg clone will clone the whole repository.

You can take a look a the sub-repository extension that allows you to have repositories inside a repository, which might match your needs.

This is straight forward with the Convert extension.