Question

Suppose we have the following (Visual Studio) projects (simplified):

• base-lib-1
• base-lib-2
• product-1: depending on base-lib-1
• product-2: depending on base-lib-1 and base-lib-2
• product-3: depending on base-lib-1 and base-lib-2 and used as a component in product-2
• product-4: like product-3

I wondered what would be a good way to organize this project structure in one or multiple Mercurial repositories. We currently use Subversion and include the dependent libraries as externals.

Now one way would be to put everything but product-1 in a single repository as all those products are always released together as a single package. I would feel most comfortable with this solution as then I would be pretty sure about how to handle the repository. But how would fit product-1 in this scheme without duplicating base-lib-1?

As an alternative I thought about using sub repositories that would be organized something like this:

• product-package-A
  • base-lib-1
  • product-1
• product-package-B
  • base-lib-1
  • base-lib-2
  • product-2
  • product-3
  • product-4

The problem with this approach is that I’ve never used subrepos so I’m not sure about any pitfalls that would arise with this solution.

For example, do the subrepos behave like SVN externals in that you can decide whether to always use the latest or a fixed revision of each subrepo?

How do subrepos behave if you make changes e.g. in base-lib-1 and product-2 at the same time? Are those handled by Mercurial in the same step or do you have to commit/push and pull/update everything manually? And how would the subrepo of base-lib-1 behave in product-package-A in this case?

How does branching work in this scenario if I want to develop a new feature branch that requires changes in multiple subrepos? Do I have to branch and merge every repository manually or is this handled by Mercurial?

Are there any other pitfalls about using subrepos to organize a large project? What is the preferred way of handling larger projects with many dependencies in Mercurial?

Answer 1

Your question is a near-perfect duplicate of a question that’s often asked here, but I can’t find a good reference in a quick search, so here you go: use the subrepos

Taking your sub-questions one at a time:

For example, do the subrepos behave like SVN externals in that you can
decide whether to always use the latest or a fixed revision of each
subrepo?

Sub-repos are pegged to a specific version, and the parent project specifies which.

How do subrepos behave if you make changes e.g. in base-lib-1 and
product-2 at the same time? Are those handled by Mercurial in the same
step or do you have to commit/push and pull/update everything
manually? And how would the subrepo of base-lib-1 behave in
product-package-A in this case?

The hg commit comma?
nd takes a --subrepos option, so you can recursively commit or not at your option (see all ui.commitsubrepos in man hgrc). Push always pushes subrepo changes.

How does branching work in this scenario if I want to develop a new
feature branch that requires changes in multiple subrepos? Do I have
to branch and merge every repository manually or is this handled by
Mercurial?

Yes, you’ll be branching and merging in each repo manually.

Are there any other pitfalls about using subrepos to organize a large
project? What is the preferred way of handling larger projects with
many dependencies in Mercurial?

Just do a test scenario first and practice. Also, make sure people have new-ish clients. This stuff didn’t really get polished UI-wise until 2.1.x