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.
Branches are indicated with certs. The cert name
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
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
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-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.
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
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
What the something part looks like is up to you, but
usually the first part is the project name (the
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
(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
- 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.