One Project One Repository: Mercurial Used Right

Mercurial LogoThis is to help those of you transitioning to Mercurial understand the right way to use it, before someone taints your innocent minds. I was recently apart of a transition from CVS to Mercurial where the Change Management (CM) department was very much involved with the switch. The early game plan was to group projects related to each other into the same repository. This was to help CM manage their builds easier, and nearly convinced everyone else that this made sense. Sadly enough it was difficult to convince CM otherwise and there still exists friction on the subject whenever new projects are transitioned. The following are some counter arguments for you to use when trying to explain to your build team to use Mercurial as intended.

Defeating the Basics of Mercurial

Here are some points that clearly defeat the purpose of Mercurial.

  • What does tip (and other tags) represent? Tip often represents the last revision of the project. With multiple projects in a repository, which project does tip represent?
  • How can I find the last revision of the project I am interested in? What do tags represent? How do I switch between versions of my project?
    – I hope raising these questions makes it clear it’s no longer trivial to use your version control system as intended.
  • CM has a repository of all the projects tagged as production version. How can it roll back to the ‘previous’ version of a project without rolling back all the other projects?
    – They can have multiple clones of the repository, sure, but then what’s the point of trying to keep all the projects into one repository.

Development Daily Problems

Daily development problems are the biggest time wasters as they can be done frequently in a day and add up over time.

  • First, lets be clear: A Mercurial repository is intended for a single project. On Mercurial’s own wiki page “Understanding Mercurial” they highlight this very point under “What Mercurial Can’t Do.”
  • Tasks are often project based. Even a high level task that would require changes to multiple projects are split into separate tasks. After committing and attempting to push for that task, you may be forced to pull changes for the other projects in that repository.
    – Even worst, you may have had changes in that project that you may now have to merge. You might not be ready to merge those changes, but you don’t have a choice as a changeset in Mercurial is the entire repository, not just a directory.
  • (Continuing from previous point) You could not use the same clone for multiple tasks. In general, the use of Mercurial is to create a clone for every task, however if we have multiple projects in a repository, we will end up with multiple upon multiple copies of projects you have no intent on changing.
    – It’s important to note Mercurial will be smart and not waste hard drive space for this (see Hardlinked Clones). However the point is there is a lot of logical waste of projects and will cause more confusion in your workspaces with the copies of projects.
  • High potential for wrongful commits. The intended idea was for related projects to be in the same repository. So there is a chance that you make some changes to a different project in the same clone while trying out different things. Especially with modular projects when trying to decide where functionality should reside. It would be common to make a change in one project, close that project from your IDE, and make changes to an alternate project. When going to commit your intended changes, you will commit those other files from the project you forgot about.
    – How does your IDE handle this? How does it resolve conflicts from files it does not have a reference to? There are a lot of questions in these scenarios that start to cause more confusion on the developer and less trust in the tools to help you but actually deceive you.

Internet Speed Problems

One of the reasons to use a distributed version control system is that you don’t have to constantly talk over the wire.  However, we still frequently do in case a computer crashes or to access code from multiple locations easily.

  • When pushing repositories to collaboration areas, you would be pushing the entire repository with all the projects across the wire. This is common for ‘branch’ repositories and creating temp repos on a server to save unready file changes.
    – Mercurial’s hard linking only works for file system clones. There is some clever mitigations to this problem (see Collaborating with Others) but doesn’t alleviate the annoyance.

Wrap Up

These points and questions are not to say there is absolutely no way to work around these, or to operate in such a way to make this work.  However it is to say you are breaking the intent, the benefits, and in all honesty the point of Mercurial. Don’t let your team be bullied into a decision that just won’t outweigh the downsides.

Useful References:
[ilink url=”” style=”info”]Mercurial Red Bean Book[/ilink] – The best Mercurial guide I have read
[ilink url=”” style=”info”]Mercurial Wiki[/ilink]
[ilink url=”” style=”info”]HG Init[/ilink] – Mercurial Introduction by Joel Spolsky

Post to Twitter Post to Delicious Post to Facebook Post to Reddit

Loading Disqus Comments ...