1.7 Branches

Sometimes, people intentionally produce forks which are not supposed to be merged; perhaps they have agreed to work independently for a time, or wish to change their files in ways which are not logically compatible with each other. When someone produces a fork which is supposed to last for a while (or perhaps permanently) we say that the fork has produced a new branch. Branches tell monotone which revisions you would like to merge, and which you would like to keep separate.

You can see all the available branches using mtn list branches.

1.7.1 Heads and merging

Branches are indicated with certs. The cert name branch is reserved for use by monotone, for the purpose of identifying the revisions which are members of a branch. A branch cert has a symbolic “branch name” as its value. When we refer to “a branch”, we mean all revisions with a common branch name in their branch certs.

For example, suppose you are working on a program called “wobbler”. You might develop many revisions of wobbler and then decide to split your revisions into a “stable branch” and an “unstable branch”, to help organize your work. In this case, you might call the new branches “wobbler-stable” and “wobbler-unstable”. From then on, all revisions in the stable branch would get a cert with name branch and value wobbler-stable; all revisions in the unstable branch would get a cert with name branch and value wobbler-unstable. When a wobbler-stable revision forks, the children of the fork will be merged. When a wobbler-unstable revision forks, the children of the fork will be merged. However, the wobbler-stable and wobbler-unstable branches will not be merged together, despite having a common ancestor.

For each branch, the set of revisions with no children is called the heads of the branch. Monotone can automatically locate, and attempt to merge, the heads of a branch. If it fails to automatically merge the heads, it may ask you for assistance or else fail cleanly, leaving the branch alone.

For example, if a fork’s left child has a child of its own (a “left grandchild”), monotone will merge the fork’s right child with the left grandchild, since those revisions are the heads of the branch. It will not merge the left child with the right child, because the left child is not a member of the heads.

When there is only one revision in the heads of a branch, we say that the heads are merged, or more generally that the branch is merged, since the heads is the logical set of candidates for any merging activity. If there are two or more revisions in the heads of a branch, and you ask to merge the branch, monotone will merge them two-at-a-time until there is only one.

1.7.2 Branch Names

The branch names used in the above section are fine for an example, but they would be bad to use in a real project. The reason is, monotone branch names should be globally unique, over all branches in the world. Otherwise, when your branch eventually gets distributed, you could get name collisions with other people’s work.

Having two separate projects with the same monotone branch names means those projects cannot be stored in the same database. In general, monotone supports storing unrelated branches in a single database, which simplifies servers. But that requires unique branch names, so ensuring globally unique branch names allows using globally accessible monotone servers.

monotone does not support renaming branches (because that would be modifying history), so choosing a good branch name up front is important. It is possible to work around this by propagating from your branch to one with a better name, but that is a painful process if there are many people using the original branch name.

Even if you are absolutely sure that your branch will never be distributed, things could change in the future!

Fortunately, we have a handy source of globally unique names — the DNS system. When naming a branch, always prepend the reversed, fully qualified, domain name of a host that you control or are otherwise authorized to use. For example, monotone development happens on the branch net.venge.monotone, because venge.net belongs to monotone’s original author. The idea is that this way, you can coordinate with other people using a host to make sure there are no conflicts — in the example, monotone’s original author can be certain that no-one else using venge.net will start up a different program named monotone. If you work for Yoyodyne, Inc. (owners of yoyodyne.com), then all your branch names should look like com.yoyodyne.something.

What the something part looks like is up to you, but usually the first part is the project name (the monotone in net.venge.monotone), and then possibly more stuff after that to describe a particular branch. For example, monotone’s win32 support was initially developed on the branch net.venge.monotone.win32 (for more information, see Naming Conventions).

It has to be noted that earlier versions of monotone enforced no restrictions on branch names. Newer versions, starting with 0.99, exclude a set of control characters though, which mostly denote either meta characters in monotone’s URI syntax or are used in globs to resolve branch patterns. These characters are ?, ,, *, %, +, {, }, [, ], ! and ^. Additionally, - is deprecated as first character of a branch name, since it is used to denote branch exclude patterns in the aforementioned URI syntax.

monotone warns on the creation of branch names which violate one of the above restrictions and gives further directions. Future versions of monotone are likely to enforce these restrictions by disallowing such branch names completely.