Re: Apologia for bzr

["Stephen J. Turnbull" <stephen@xemacs.org>]

Eli Zaretskii writes:

 > At least in Emacs we have an excuse that the bulk of the
 > terminology developed when no other software provided any similar
 > features; there's no such excuse for git (or bzr or hg).

You're wrong about git, you're arguably right about bzr and hg.

Git is fundamentally different from bzr and hg, almost as different as
it is from CVS and RCS.  Git is designed for use cases like "git
filter-branch", it's easy enough to implement it as a shell script
(though it would be slow), and probably it was prototyped that way
(although I would write the prototype in Lisp, not shell).  I really
wouldn't want to try to do that in hg or bzr: although it could be
done, it would be unusably slow (because they don't have a separate
index, so the work has to be done in-tree-on-disk, rather than only on
metadata in memory).

 > Anyway, there's a big difference here: in Emacs documentation,
 > every term is explained before it is used, and rarely used terms
 > have cross-references to where they are described.

I bet you can dip into any number of Info nodes where the terms
"buffer" and "window" are used without definition.  The git "index" is
equally fundamental to git.  It's what makes things like "git reset"
make sense.  It's what explains the sometimes disconcerting behavior
of git diff with respect to "git add"ed files.  It's what makes
staging workflows (which some people love even if you can't figure out
why they could love them :-) possible.

 > > > Here, a typical example from git-commit:
 > > > 
 > > >   DESCRIPTION 
 > > > 
 > > >   Stores the current contents of the index in a new commit along with
 > > >    a log message from the user describing the changes.
 > > > 
 > > > Huh?  "Contents of the index"?  I used to know what commit was, now I
 > > > don't.

Sure you do; commit hasn't changed.  What you now know is what the
index is: a data structure that contains the same information as a
commit, but isn't a commit and isn't a working tree, either.  It has
an independent life of its own.  Implicitly, it is volatile, and "git
commit" makes a persistent record of its current state.

Of course hg and bzr use indexes, too, but they're not exposed to the
user: they only exist during the process of committing.

 > You are missing the point: I didn't want a tutorial.  I use VCSes for
 > many years, and dVCSes for some; I already know what it means to
 > commit a changeset and what is the basic workflow of using a dVCS.

But I think you've misstated the case here.  Development has
workflows, and dVCS usage is adapted to them.  It doesn't make sense
to talk about "*the* basic workflow of using a dVCS".  You're actually
talking about *your* basic workflow, and how you use a dVCS in that
workflow.  Other people's workflows vary wildly, and from the point of
view of dVCS usage, they're just as basic.

 > "Recording a commit"? what's that?  And is "commit that has the exact
 > same tree as its sole parent commit" a complicated way of saying "no
 > changes since the last commit", or is there some important subtlety
 > here that I'm missing?

It's probably not important to you, so I won't go into detail, but
there are several subtleties that are missing from the simple
expression "no changes since the last commit".  But this is again
missing an important point about how git is different:

 > Even bzr's commit docs does much better:
 > 
 >   --unchanged   Commit even if nothing has changed.

This makes a lot of sense in Bazaar, because Bazaar makes it hard to
work nonlinearly without using multiple workspaces.  Nonlinear
workflows in a single repo/workspace are what git is designed for.  In
a nonlinear workflow, "nothing has changed" is meaningless until you
answer the question "since *when*?"  "The parent commit" is the
precise and meaningful answer.

 > I want some decent reference documentation.

AFAICT, you want your dVCS to be Bazaar.  Nothing wrong with that
(while I really dislike bzr, I don't think it's dead, at least not
yet, and that dislike is a personal thing, no reason why you should
change your mind).  But the overwhelming majority of posters (and I
suspect that means the majority of Emacs developers) want git, and git
is not, will not be, and should not be, Bazaar.  Sorry!