Does a mercurial subrepository have to be a subdirectory of the main repository?

Question

My project is made up of code in the following locations

C:\Dev\ProjectA
C:\Lib\LibraryB
C:\Lib\LibraryC

Presently each of these folders is a completely independent Mercurial repository. Project A changes all the time, Library B and Library C change rarely.

I currently tag each version of Project A as it is released and (when I remember) put a corresponding tag in the Library B and C repositories.

Can I improve upon this by using subrepositories? Would that require me to make Library B and C a subdirectory of Project A?

If Library B and C must be subdirectories of Project A what do I do if I want to start a Project D that uses Library B but isn't otherwise affiliated with Project A at all?

Answer 1

If Library B and C must be subdirectories of Project A what do I do if I want to start a Project D that uses Library B but isn't otherwise affiliated with Project A at all?

Any project can exist both independently and as subrepository of another project at the same time. I'll explain by suggesting a workflow.

First of all, each of your projects (A, B, C) should have a blessed repository that is published somewhere:

You could run hgwebdir on your own server, or make use of a Mercurial hosting service like Bitbucket or Kiln. This way developers have a central authorative point to pull/push changes from, and you have something to make backups of.

Now you can make clones of these repositories to work on in two different ways:

• directly clone your project. For example:

  hg clone http://bitbucket.org/LachlanG/LibraryB C:\Lib\LibraryB
  

• and/or create subrepository definitions by putting a .hgsub file in the root of ProjectA with the following content:

  libraries/libraryB = http://bitbucket.org/LachlanG/LibraryB
  libraries/libraryC = http://bitbucket.org/LachlanG/LibraryC
  

These subrepository definitions tell Mercurial that whenever Project A is cloned, it also has to put clones of Library B and Library C in the libraries folder.

If you are working in Project A and commit, then your changes in libraries/LibraryB and libraries/LibraryC will be committed as well. Mercurial will record which version of the libraries is being used by Project A in the .hgsubstate file. The result is that if you hg update to an old version of the project to see how things worked last week, you also get the corresponding version of your libraries. You don't even need to make tags :-)

When you hg push the Project A changes to the blessed repository, Mercurial will also make sure to push the subrepository changes first to their own origin. That way you never accidentally publish project changes which depend on unpublished library changes.

If you prefer to keep everything local, you can still use this workflow by using relative paths instead of URLs in the subrepository definitions.