Can I clone part of a Mercurial repository?

Question

Is it possible to clone part of a Mercurial depot? Let's say the depot is quite large, or contains multiple projects, or multiple branches, can I only clone part of the repo?

E.g. in Subversion, you might have trunk and branches. If I only want to get trunk (or one of the branches) I can just request [project]/trunk. If I clone the hg repo I'll get trunk and all of the branches. This might be a lot of information I don't want. Can I avoid getting this?

Alternatively, if I want to have multiple projects in one hg repo, how should I do this? I.e. so that I might just get one of the projects and ignore the others.

Answer 1

Mercurial and Git only permit cloning on the entire repository. Thus it is recommended that each project gets its own repository.

Mercurial has a forest extension to ease having a "forest" for project repositories. The extension keeps each project in a separate repository, but provides options to update/push/pull all the forest repositories together.

Answer 2

In my knowing, that's not possible. But compared to Subversrion, cloning the whole repos may not be slower than just a branch from SVN.

Quoting from http://mercurial.selenic.com/wiki/UnderstandingMercurial:

Many SVN/CVS users expect to host related projects together in one repository. This is really not what hg was made for, so you should try a different way of working. This especially means, that you cannot check out only one directory of a repository.

If you absolutely need to host multiple projects in a kind of meta-repository though, you could try the Subrepositories feature that was introduced with Mercurial 1.3 or the older ForestExtension.

Answer 3

@Nick said:

"This is a pretty big omission since a lot hosting sites only offer one repo. With svn I can effectively have as many repos as I want by only taking one branch from the main one. The subrepos sound like a hack."

Subrepos (aka submodules) are not as ideal as "narrow clones" its true. But at least for having many distinct projects in one hosting site's repository, you can have multiple code-bases in one repository. This won't allow you to slice up different sections of one repository / sub-directories of a project , but it will let you manage multiple projects. What you do is have lots of named branches each rooted at the empty (or null) changeset (i.e. they have no common root revision). It can get a little messy to track the branches but it does work.

For example:

hg init
hg branch project-1
# Changes, commits, repeated as needed
hg update null
hg branch project-2
# Changes, commits, repeated as needed

You now can see all your projects:

> hg branches
project-2                      5:42c2beffe780
project-1                      2:43fd60024328

The projects are unrelated (though you can merge them):

> hg debugancestors
-1:000000000000

Most usefully: you can clone only the project you want, and the others won't mix in:

> hg clone <repository> -r project-1

The graph for this would look something like this (hg log -qG):

@  5 | project-2 | {tip}
|
o  4 | project-2
|
o  3 | project-2

o  2 | project-1
|
o  1 | project-1
|
o  0 | project-1

You can do this for as many projects as you need, listing each with hg branches, and jumping between them with hg update. This takes some care, because named branch support isn't perfect. It isn't always intuitive for one thing (read about hg clone -u in Mercurial 1.4 -- the pre-1.4 behavior is surprising when cloning). But it does work.

Answer 4

@Nick

"E.g. in Subversion, you might have trunk and branches. If I only want to get trunk (or one of the branches) I can just request [project]/trunk. If I clone the hg repo I'll get trunk and all of the branches. This might be a lot of information I don't want. Can I avoid getting this?"

Absolutely. Just use hg clone -r <branch> and get only the branch you want. If you have lots of branches, you need a -r <branch> for each one. <branch> doesn't have to be a named branch: you can simply have multiple unnamed heads (or named heads using bookmark, though those still aren't perfect, because currently they don't show up with push/pull/clone).

Keep in mind that in DVCSes, Mercurial among them, branches are often short-lived and merged back into each other frequently. If you pull a branch you will still get the common history it has with any other branches.