presenting the fundamental abstractions

[Matthew D. Fuller]

On Wed, Sep 12, 2007 at 09:03:10AM +1000 I heard the voice of
Andrew King, and lo! it spake thus:
> 
> Unfortunately, I came up with 4 components, not 3, so that is a bad
> start :(

Oh, absolutely.  I ignored Revisions in this thread, though not in my
mental model.  For somebody coming from git or mtn or one of the
current gen DVCS's, emphasis on that is unnecessary, but for somebody
coming from CVS/SVN, or from no VCS, it's definitely needed or else
it's difficult to explain much of anything else.  The Revision really
is the first-class object; everything else just refers to, creates, or
stores them.


I'm short on time, so just a few notes.


> A revision is a set of changes to one or more files, with associated
> metadata (such as the author).

And importantly, the parent[s].

And revisions are states, not changes.


> and is in fact, the set of files that would be produced if you
> applied all the revisions in that branch in order.

See above about changes vs. states.


> It is effectively a tool for caching revisions for sharing between
> branches.

I don't like this, because it turns your saying 'repository' into
really meaning 'shared repository'.  Now we're back to memorizing
special cases and composite setups.


The fundamental "3 pieces" abstraction concept I'd wish to get across
in such a document condenses to:

    There are 3 pieces:

    1) A repository holds revisions.
    2) A branch defines a series of revisions [sorta, mod revision
       discussion about parents].
    3) A working tree holds files you can edit.

    To work in bzr, you need all 3.  They can all be co-located in the
    simple case (standalone tree).  They can all be separated (a
    shared repository containing branches, which you work on from
    checkouts elsewhere).  2 can be together with the other separate
    (working tree colocated with a branch, inside a shared repo, or a
    non-colocated checkout of a branch with internal repository...
    conceptually, I guess you could even colocate a repo and wt, with
    the branch being elsewhere, though that colocation would just be
    coincidental; that would be a way to implement named branches in a
    git-ish workflow).

Once you internalize that, there are very few special or odd cases in
the commands; you just have to realize what each command does and what
pieces it affects, and The Answer Is Obvious(tm) (mod bugs, which are
unpleasantly far from extinct).


> Why does a branch share the "has a working tree" or "doesn't have a
> working tree" aspect of its repository (if it has one?).

It doesn't 'share' per se, just inherits a default.


> [...] foreign branch.

I'd avoid the 'foreign branch' terminology.  It usually refers to
working with foreign VCS's.


> # Why does checkout do 2 seemingly very different things? This seems
> to cause a lot of confusion.

It does, and I think that's because it's mal-explained.  checkout only
does 1 thing; it creates a working tree for a branch.  Whether that WT
is colocated with the branch, or whether it's heavy/light, are
entirely details.  Too much effort is spent explaining those details
(and causing immense problems with 'Oh, a checkout is really a branch,
except when it isn't') when people would be much better off just
memorizing my second sentence.


> # Why can't annotate work on a remote branch?

Can't?  It _can_.  It _doesn't_, though.  It's a combination of
factors; annotate doesn't work on branches, it works on WT's, and you
can't open a remote WT.

<https://bugs.launchpad.net/bzr/+bug/90049>


> # How do I remove a working tree from a branch that has one?

% bzr remove-tree


-- 
Matthew Fuller     (MF4839)   |  fullermd at over-yonder.net
Systems/Network Administrator |  http://www.over-yonder.net/~fullermd/
           On the Internet, nobody can hear you scream.