Skip to content

Hg subrepositories: a how-to guide for the “svn:externals” junkie (Part 3)

This post summarizes the Mercurial subrepository vs the Subversion externals experience. This is the third and last post of a multi-part article about Mercurial subrepositories. Please make sure you read Part 1 and Part 2 before reading this post.

In a few words, Mercurial subrepositories are very similar to Subversion “svn:externals” and can be used pretty much the same way. However, there are some differences in the workflow, because of the distributed nature of Mercurial. Here are the main differences from Subversion:

  • You always work in a copy / clone of a remote shared repository.
  • You may commit changes multiple times, but those changes are not visible to others unless you push to the remote shared repository.
  • A commit + push in a subrepository is treated as a local change in the top-level root repository. To make the root change permanent, you have to do a commit + push of the root repository as well.
  • A pull from a remote repository just downloads the latest available changes. In order to apply/merge the changes, you have to manually update your working copy.

On good thing about the pull+update workflow is that, it guards against accidentally losing local changes and allows you to do code merges at your convenience.You can also revert an update and continue in your local copy when an update breaks a lot of code and requires hard manual merge labor. You can update your working copy again later, when you are ready for the code merge.