Bazaar Theory

This article attempts to give an in introduction to distributed VCS in order to explain HelenOS Bazaar workflow.

Revision Graph

Unlike with a centralized VCS the revision history is not linear, but instead it is a directed acyclic graph. Eeach node in the graph represents a revision (or equivalently it represents a changeset). The nodes are connected by arrows. Exactly one node has no parents (the initial commit). Every other node has one parent (regular changeset) or two parents (merge changeset). The two parents are not equal. When you merge in Bazaar, you always merge to the current branch (we will note it as left parent) from another branch (right parent).

There is also always at least one node which has no children. Every such node is called head (do not confuse with the main HelenOS repository). In a Bazaar branch there is usually just one head. If you start from the head and go against the direction of arrows, always following the left parent if there are two, until the initial commit, you will traverse the main branch of the repository. The main branch of the central repository is called the mainline.

Every Bazaar branch has its own view of the repository's history. More specifically, the order of nodes' parents can differ between repositories. This also means that the main branch of A may be different from the main branch of B (although the set of revisions is the same).

As long as the set of revisions in repository A is a subset of the revisions in repository B, you can pull from B to A. If the revisions A form a superset of revisions in B, you can push from A to B. As long as A and B have some common ancestor, you can merge from one to another or vice versa.

Pushing and Pulling

It is important to note that pushing from repository A to B (or pulling to B from A) will change all the history in B to match with the history in A effectively overwriting it. The actual thing that changes is the order of nodes' parents. This also changes the idea of what is considered the main branch. For this reason you must never push to the main repository if the main branch in your repository is not a superset of the main branch in the main repository.

When you create a new branch, it will be consistent with the main repository. However, if you merge the mainline head into your branch, then you used the mainline as the right parent. This means that the mainline is not the main branch in your repository (because that passes through the left parent). In this case you must not push to the main repository!

Merging a Feature Branch into the Mainline

Since it is not possible to merge directly to the central repository M, we must do the following in order to merge our private branch in A: First create a clone M_C of M with bzr branch. Then merge A into M_C. This means we take the mainline in M_C as the left parent and the feature branch in A as the right parent. In the end the main branch in M_C will be a superset of the main branch in M (the mainline). Now we are free to push from M_C to M.