Mercurial Branches versus Kiln Branches


There is a difference between Mercurial Branches and a Kiln “Branch”.

Mercurial has a specific command, called hg branch, that creates something called named branches. Mercurial tools historically did not interact with named branches in a user-friendly manner, and named branches have historically had very confusing and hard to understand behaviors: closing and abandoning branches was problematic, the meaning of the tip changeset and your tags became extremely complicated, and so on. Although, there is some argument that having some type of named branches is very useful.

What Kiln attempts to do is to obviate the need for named branches by making it very easy to have lots and lots of clearly named and well-organized related repositories on the server. We’ve opted to call those repositories “branch repositories”, since their goal is to allow you to have a branch for experimenting on a feature/storing code for later review/etc. All repositories in Kiln, whether branch repositories or central, are full-standing, independent, and (by default) only have the default branch. (You’ll see it with a green background right next to tip when you’re viewing a repository’s history.) In this way, Kiln “branch repositories” function much like “forks”.

What we encourage you to do is to keep separate branches of development in branch repositories/forks in Kiln off the main repository, rather than using Mercurial’s named branches. In addition to the fact that tools support this workflow better, it becomes a lot easier to know what branch/fork you’re working with (just see where you cloned from), becomes trivial to discard changes (delete the “branch repository”/fork), and makes it easy to try experiments without cluttering up the “real” repository’s history.

So: we strongly encourage you not to use Mercurial named branches. We instead encourage you to use Kiln’s “branch repositories”/forks to make branch management easy, and to use a clone of a “branch repository”/fork when you need to contribute to a branch/fork.

If you really do want to use named branches, Kiln fully supports them. You can filter to just a single branch head by selecting a branch from the “branches” drop-down menu when viewing a repository’s history.