Changes between Version 4 and Version 5 of BazaarTheory

Timestamp:

2009-08-17T19:00:54Z (15 years ago)

Author:

Jiri Svoboda

Comment:

Replace nonsense with some sense.

BazaarTheory

@@ -9 +9 @@
 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 (this is what {{{bzr log}}} shows you). 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).
+Every Bazaar branch can have a different head. This also means that the main branch of ''A'' may be different from the main branch of ''B'' (although they may represent identical source trees).
 
 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.
@@ -15 +15 @@
 == 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.
+Generally speaking, the effect of a push from ''A'' to ''B'' (or pull from ''B'' to ''A'', which is the same) is to introduce into ''B'' all changesets from ''A'' which are not already there. In Bazaar this can only be done if the resulting repository contains only one head (such as when ''A'' contains a merge changeset has the head of ''B'' as one of its parents).
 
-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!
+The push or pull operation in Bazaar, however, has one more effect. ''B'' will get a new head... the head of ''A''. This is the reason why you must not push from a (diverged) feature branch to the main repository. The main repository would inherit your repository's head and your feature branch would become the mainline (and the history of your branch will become the history of the mainline), which is very bad.
+
+== Merging ==
+
+In a general distributed VCS a merge changeset consists of the references to its two parents and, possibly, a patch that resolves merge conflicts. A merge operation consists of creating the merge changeset. In Bazaar, however, a repository can only have one head. This means you cannot get to the situation you would expect before merging (two heads).
+
+Thus, the merge operation in Bazaar works with the current repository as the left argument and another repository as the right argument. It actually consists of two operations:
+
+ * pulling necessary changesets from the other repository and
+ * creating a merge changeset with the current head as the left parent and the head of the other repository as the right parent.
+
+After this Bazaar will let you resolve possible conflicts and commit the merge changeset. We end up with a valid Bazaar branch that has only one head.
+
+== Merging Mainline Changes to a Feature Branch ==
+
+This is easy since you have direct access to your repository. You simply go there and run {{{bzr merge}}} with the main repository as the argument.
 
 == Merging a Feature Branch into the Mainline ==