Re: Strange message from "bzr pull"

[Stephen J. Turnbull]

Óscar Fuentes writes:
 > Karl Fogel <address@hidden> writes:
 > 
 > >>BzrForEmacsDevs is not simple enough for people who have CVS
 > >>incorporated into their DNA. IMHO it lacks some clear explanation of
 > >>the new concepts (revisions, branches, merges, histories, divergence,
 > >>etc)
 > >
 > > Several places in the document (including the The Other Resources
 > > section) already point to
 > > http://wiki.bazaar.canonical.com/BzrForCVSUsers, which has the material
 > > you describe.
 > 
 > That document is too shallow, barely qualifies as an introduction.

http://doc.bazaar.canonical.com/migration/en/survival/bzr-for-git-users.html
may contain some useful information.  It assumes substantial
familiarity with git, so the very basic stuff is not given there.

 > It doesn't hint at what a revision, for instance. Nobody that reads
 > that document knows that the key information that makes DVCS
 > possible is what you see with
 > 
 > bzr log --show-ids

I agree that the concept that a revision has a universally unique ID
needs to be mentioned, and that a branch knows which IDs it contains,
and can therefore reproduce by updating a working tree.  But the
sentence I just wrote is horrible, nobody who doesn't already
understand will learn anything from it :-), and I don't think a
reference to "--show-ids" will help much.  You need to explain what
those IDs mean.  Specifically, they represented directed arcs in a
graph.

I think that for Emacs developers it may be useful to think of a
"commit" or "revision" by analogy to the Lisp cons.  The "car"
contains a pointer to the revision metadata and the actual content
(files).  The "cdr" is the parent revision.  The obvious part of the
generalization is that the "cdr" may be multiple-valued in the case of
a merge commit, which has multiple parents.  To continue the analogy,
a branch is like a Lisp list, with the root commit being the final
"cons" which has "cdr" of "nil" (ie, it has no parent).

The less obvious part of the generalization is that in a DVCS the
pointer(s) in the "cdr" (and in the "car") are *universal*.  In the
Emacs Lisp implementation those are machine addresses, and they are
implementation details that are only exposed in the debugger.  But in
DVCS, that cannot be so: the communication protocol between different
branches (even on the same host!) needs to use them.  *Every* bzr
branch either assigns the same universal meaning to the id, or it
knows that that id is not part of the branch.

It's true that the information about revision IDs and content IDs
locally may not be of great interest at the moment.  However, they
will automatically be universally valid if you ever push from your
branch, or somebody pulls from it.  It is the universality that makes
*distributed* VCS possible.

N.B.  With respect to git, this description is a pretty accurate
description of the implementation.  For Mercurial and Bazaar, the
implementations are substantially different to support various
features of each DVCS, but all of them do have a concept of the
"history DAG", which is represented by links among "revision objects".