Question

I am new to mercurial and I am trying to grok the whole branched repository vs. named branch issue.

It seems that the mercurial dev team and most of the experienced users have settled on the branched repository side. I have landed on the named branch side, at least for my development team. This confuses and concerns me.

Most of what I can find online is just vague hand waving and name calling: named branches are broken, hard, confusing, poorly supported, etc. The specifics I have dug up do not seem to support any of that. Could it be a cultural or historical bias due to the relatively late addition of named-branches?

There is some inherent complexity in branched development, but it seems that the primary difference between the two modes is that the branched repository model hides branches from you based on which repository you are looking at. From my perspective, this seems to make it more difficult to see the big picture and to slightly increase the complexity of things.

My concern is all the things I don't know about Mercurial that I may not learn about until it's too late.

Can some of you experienced Mercurial users give specific pros and cons of the two models?

---

4/30/08 update: We have been using named branches in our branch-per-feature model for over two months. This has worked very, very well for us. No gotchas. No roadblocks. There is no other feasible way within Kiln/Mercurial to cherry pick features as they are validated, which our development process requires.

Answer 1

First, to assuage your fears: named branches have been in Mercurial since the beginning, and are actively used by the Mercurial and TortoiseHg teams for developing Mercurial and TortoiseHg, so they're well-supported and not going anywhere. If you keep using named branches, you're certainly "safe," from a stability and support standpoint.

Now, to elaborate on Jason's answer:

There are two reasons that people generally stay away from Mercurial's named branches: they're "permanent", and they break a lot of workflows in older versions of Mercurial.

By saying that named branches in Mercurial are permanent, I mean that they are always in the revision history. In Mercurial, when you make a commit on a branch and push it, that commit is part of the repository's history forever. What a lot of people wanted with Mercurial branches were throw-away branches that wouldn't show up in the history once they were done, and that you could just obliterate if the experiment failed. If your branch is a clone to somewhere else on disk (or a Kiln branch repository), you can just delete it if you decide you don't like it, and it won't clutter up your history or make your repository bigger. If it's a named branch, it's going to be there, even if you decide never to merge it. That's why Mercurial itself encourages named branches for long-running branches, but discourages their use for feature branches. It's a social, not technical, reason.

These social problems are technical problems in earlier versions of Mercurial, though. In older versions of Mercurial, using named branches breaks a lot of common Mercurial behaviors. Talking about the tip changeset stops making sense; on older versions of Mercurial, hg fetch and hg merge would suddenly always require explicit arguments on what you wanted them to do; and commands like hg up with no arguments became dangerous, happily jumping around branches without warning.

Over the last year or so, the Mercurial team has made a huge number of improvements to named branches. You can close branches without merging them, hg up will go the head of the current branch, hg merge will default to merging heads within a branch (rather than demanding explicit parameters 100% of the time), and so on. Working with named branches now generally does not cause any problems.

For Kiln, we still discourage using named branches because older versions of Mercurial do not handle them well, because we think that branch repositories and local clones are an easier-to-grasp concept, and because they work for most people (i.e., people who do not work routinely with multi-gigabyte repositories). As long as you don't have truly massive repositories or don't clone locally often, then Kiln's Activity Feed, push histories, "Outgoing" tab, and similar features, give you easy, rich monitoring of all commits in a project across repositories, without the mental overhead of named branches, and without any concerns for users on older versions of Mercurial.

If you understand how named branches work, understand the issues involved, and you want to use them, then go ahead. Mercurial and Kiln both fully support them and will continue to do so, and we have some good ideas on how we can make Kiln handle them better in upcoming versions (such as filtering by branch, and pushing branches in a reasonable way for server-side push). But we still think that branch repositories are a better solution for most users of Kiln.

Answer 2

To get you started, I borrowed this from one of Benjamin's earlier answers:

Mercurial's named branches are analogous to long-running branches in Subversion or CVS. Third-party Mercurial tools in general do not interact with named branches in a newbie-friendly manner, and named branches have historically had very confusing and hard to understand behaviors: closing and abandoning branches can be problematic, the meaning of the tip changeset and your tags becomes extremely complicated, pushing creates the warning you're seeing, and so on. For that reason, we actively discourage using them in Kiln, and even ship an extension called nobranch with Kiln to discourage new users from using hg branch

To expand on that a little:

Named branches are harder to work with because you have to do more/different work in Mercurial to make use of them. You have to grok a new command set for controlling them. You have to be very conscious of where you are in the repository (on what branch at what revision) when you are working and there are no helpful clues (like separate directories in the branched repo model). That puts you at greater risk of making a mistake while developing and putting changes in the wrong place. And, in the long term they can create even more confusion when trying to understand the "current" state of your repository because the tip revision loses it's meaning (it is just the latest revision, but it could be on a branch somewhere).

Because repositories can share history now, and merges can take place between them, it opened the door to simplifying the usage model. You interact with branches just like any other repository. No special commands. Sure it adds a little time overhead at the start, but extremely little cognitive load.

As far as branches being "hidden", I would argue that the visualization that Kiln provides (the hierarchical graphical central/branch repo model) exposes this in a better way than Mercurial's tools for using named branches because it is usable by everyone (well mostly everyone) without having to fully understand the inner workings of Mercurial. You're right that it's not in the repository, and we would like to get this closer to the client, but our hope is that as people start to get used to Kiln, they will stat to "live" in it. We certainly have.

Answer 3

As my team looks at using Mercurial and Kiln the named-branch capability seems to have another implication...

Looking at the scale of some of our projects, I believe we will require the use of sub repositories. subrepos require a (single) location to be specified in the .hgsub file.

I'm guessing that any given repo will have some array of branches aligned with workflow...likely stable/test/dev (or some such). This will obviously include subrepos. If I use a cloned-branch (different locations) scheme for these three, which location do I put in the .hgsub of my parent project(s)?

If I use the stable release for all of my subrepos (the ideal scenario), things are fine unless I want to do development on my subrepo as part of the parent project. I see this being fairly common.

If I use the dev location for subrepos, I'll likely need to change this as I merge my project up to test and most definitely to stable (I cannot have a stable parent project with subrepos pointing at development branches). Not to mention that many of my subrepos probably need to be on stable and not dev.

If I use named branches for all repos then: - I can use one path in the .hgsub file - I can immediately see all the workflow - I can 'hg up dev' if I want to modify some subrepo code

Granted, there is more complexity, and if I don't know what I'm doing I can easily commit to the stable branch (or make a branch from the wrong branch for that matter). I am thinking we'll create some hook scripts to help enforce working on the right branch.

As I said, we are looking at using Mercurial and Kiln and we do not have experience using this model. That is just what we've come up with so far.

G