Newbie documentation: Bazaar Merge?

[Stephen J. Turnbull]

Ben Finney writes:
 > "Stephen J. Turnbull" <turnbull at sk.tsukuba.ac.jp> writes:
 > 
 > > Multiple named heads is an accident waiting to happen in Mercurial,
 > > and may very well be one in Bazaar as well, depending on the
 > > implementation and documentation. But that is *because* of the "One
 > > Explicit Head Per Workspace" philosophy (which Mercurial also
 > > subscribed to at first). In git colocating branches is [...]
 > 
 > Why is "one explicit head per workspace" contrasted with "co-located
 > branches"? I thought that, even with co-located branches, there's
 > *still* only one explicit head in the workspace: the head of the current
 > branch.

It's rather incoherent terminology; I should have avoided it.

You seem to be associating "explicit head" with "the head referring to
the parent of the next commit".  Of course there can be only one of
those, because it's normally implicit :-) (you don't refer to the
current head when you invoke a commit command).

But what I mean by "explicit" is "named bare".  In Bazaar, it's rather
unusual to operate on a head by itself.  Rather, the focus is on the
branch, and the current head is only one part of the metadata of that
branch.  git doesn't *have* a concept of branch, in fact, only named
bare heads.  A commit's name is called a "ref" in git; a "head" is a
ref which can become the parent of a new commit, in which case it is
automatically updated to point to the new commit.  That is a complete,
precise definition of "head" in git.  This lack of metadata *in* the
head by comparison with Bazaar's branch is what I mean by *bare*.
"The" head in git is by convention .git/HEAD, which recursively refers
to another head (this is the implicit parent for "git commit"), while
other heads by convention are written to files in .git/refs/heads/.
By *name* in "named bare" I mean the head's name as a file.

So in git colocating "branches" is trivial.  Simply change the
contents of .git/HEAD in your workspace, and you've changed branches.
(This isn't a checkout, which requires changes to the workspace as
well; it's just a change of the current branch.)  Since in git
"branch" is *defined* by the *convention* of making the new commit a
child of HEAD, any other metadata must be contained in a dictionary
keyed by head names.  And it's all optional; you pretty much have to
maintain things like default push and pull locations yourself.  (This
is not as horrible as it sounds because of "tracking branches" created
automatically by "git pull" and certain other defaults set up by the
"git clone" operation, but it's not quite as convenient as Bazaar's
way of doing things, either.)

On the other hand, in Bazaar even defining "colocated branches" is not
trivial because of the baggage that branches carry with them, and the
amount of implicit setup that Bazaar does for you when you branch.  Is
a colocated branch a branch, even?  Or should it be a different
structure which refers to "real" branches?  If it is a branch, what
metadata should Bazaar update?  Does a colocated branch have its own
metadata?  Etc.  I have few intuitions about good answers to any of
those questions.