Both Mercurial and BitBucket make one fundamental assumption: 1 repo = 1 project.

If I have a project that has a dependency (a library) which is shared by many projects, this assumption gets in the way. Now it is no longer possible to have a separate BitBucket page for each project while still being able to commit atomic revisions to multiple projects.

If I put all the projects into one repo, they all become one “project” on BitBucket. If I put them in separate repos, it is no longer possible to know which version of the library project was in use at revision X of a dependent project.

How is this situation normally solved on BitBucket, or is there explicitly no support for this common scenario?

3 Answers 3


Mercurial has the Subrepositories feature which essentially do configuration management of your other repositories. It is extremely easy to setup.

All you have to do is create the .hgsub file like this:

src/app         = https://bitbucket.org/<user>/app
src/framework   = https://bitbucket.org/<user>/framework
src/library     = https://bitbucket.org/<user>/library

One repo per line, path to the left, URL to the right. When you commit, Mercurial will fetch those repositories and prompt you for credentials. After that, and each time you commit, the .hgsubstate file will change automatically depending on the states of your subrepos (revision, branch, or whatever you have selected in each one).

27442cb5903128c6f817e2943030b9297a0d569f src/app
4d11fabc8a6121ceb07e11ddd81fb1e4ad2f5980 src/framework
8d6f570174a535839c189cf84d04f5ae5253a253 src/library

The left side represents the hash, the right side the path to the repo. This file is versioned, but as I mentioned earlier, it gets edited automatically by mercurial.

So if you make a commit on src/app, the hash is going to change. When you are happy with the combination of states in each subrepo you commit the parent repo. *BLAM!*, you have configuration management.

Edit: I just discovered the Hg Guest Repo extension and I think this is just what you need, quoting:

Extension for enterprises needing to handle modules and components

Hg subrepos do not handle the sharing of components well, due to 
the recursive merge from the top (super) repo and requirement to 
lock at a specific version.

Guestrepo's goal is to overcome these limitations.

The guestrepo extension does not change any existing Mercurial 
 behavior. It only adds new commands.
  • Now if I make a change to a library, and there are 47 projects depending on that library (including, perhaps, other libraries which themselves have projects depending on them etc.), will they all update automatically? It sounds like I’d have to go hg pull; hg update an exponentially-growing number of times — are you sure this scales?
    – Timwi
    Oct 2, 2012 at 1:54
  • No, and actually this is a very important point and something asked often. You want to have control here, if you can update recursively that would mean you would then have to check your code against all updated dependencies. Keep in mind hgsubstate is the one that checks for everything to be consistent, a recursive pull would mess that up. Now, if you go to the Subrepositories official page it says that Subrepos are a feature of last resort: you don't have to use a subrepo for each single dependency. If you make changes to a library, each one of your projects can point to the state they need. Oct 2, 2012 at 5:07

Both Mercurial and BitBucket make one fundamental assumption: 1 repo = 1 project.

I think you are wrong, at least about the Mercurial part. I have multiple projects inside the same Mercurial repository and it works very well for me (and for many others).

As for BitBucket, it is built around the concept of repositories and it doesn't go much further than that. It provides a basic wiki and bug tracker, but it is not a project management tool. If you need a separate wiki page per project, you should consider using an external wiki or project management tool.

  • This is not about wiki pages. The point is that if you put everything into one repository, then in your checkout you can only have all or nothing, and from BitBucket you can only download all or nothing.
    – Timwi
    Oct 2, 2012 at 0:06
  • 1
    If you have many dependencies between projects, don't you have to download all of them anyway ? Oct 2, 2012 at 0:14
  • No. If you have two projects A and B, and they both use a library L, you always need only A and L, or only B and L. If you have 47 projects (some libraries, some not) with complex dependencies between them, I expect a computer to be able to figure out what it needs for any particular project P.
    – Timwi
    Oct 2, 2012 at 1:56
  • Differently put: if you saw an interesting open-source tool on BitBucket, and you wanted to download it, how would you feel if you had to download 47 other projects that are mostly completely unrelated?
    – Timwi
    Oct 2, 2012 at 1:58
  • @Timwi If you weren't using subrepos you would have to download them nevertheless Oct 2, 2012 at 13:10

git has submodules

looks like hg has subrepository

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.