Re: Apologia for bzr

[Stephen J. Turnbull]

Eli Zaretskii writes:

 > > 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).

And I replied:

 > > You're wrong about git, you're arguably right about bzr and hg.
 > 
 > What, git was the first VCS, and needed to invent a new terminology?

Not the first VCS, but certainly a leader in the generation of VCSes
first to provide the features that got new terminology (index, fetch,
pull, push).  For older features (such as commit, diff, and merge) it
uses the traditional terminology.

 > > Git is fundamentally different from bzr and hg, almost as
 > > different as it is from CVS and RCS.  [...]

 > What does this have to do with clear and comprehensible
 > documentation?

dVCS, being fundamentally different from cVCS, needs new terminology
(eg, at least one of the three concepts "commit", "push", and "commit
and push" needs a term not used in cVCS).  Similarly, git, being
fundamentally different from bzr and hg, *needs* more new terminology
than they do, specifically "index" and "reset".  Inventing it was not
avoidable.  The rest of that paragraph was justification for the claim
that git is different.

 > I said "rarely used terms".  Frequently used terms need to be
 > understood in advance, by reading the preceding chapters.

"Index" and "commit object" are used frequently in git documentation,
although perhaps not in the parts you have read.

 > In any case, buffer and window can be intuitively understood, much
 > more than "index" and "staging".

In fact, some people find "buffer" and "window" very unintuitive (they
don't know what a "buffer" is, they think they're looking at a "file"
or "document", and "window" means a GUI object, not a subdivision of
the GUI object).  Others (me, and at least one other person has
testified to finding "staging" very intuitive) find "staging" and
"index" quite intuitive, thank you very much.

 > > The git "index" is equally fundamental to git.
 > 
 > But there is a way to explain what a commit does without ever
 > mentioning the index, certainly not in the sentence that _defines_
 > what a commit is.

Sure, but to define commit in git, it also needs to describe what a
commit object is, which is (basically) a file containing a copy of the
index.  If you know what the index is, then you know what a commit
object is, and then you know what a commit is.  Understanding this is
important to understanding the performance characteristics of git, as
well as the operation of some features not available in other dVCSes.

 > > 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.
 > 
 > No, I don't know any of this, because it wasn't explained, not even in
 > a few words that would help me make it past the obstacle.

git help glossary

I agree that's inconvenient compared to an Info link, and that the
current version of the top-level git man page (which just lists the
other man pages) is pretty hideous -- IMO it ought to contain about half
the material in the glossary plus a description of the structure of the
git object database with a few key terms explained with reference to
the object database operations they perform.

 > No, I'm talking about *the* basic workflow: make changes, then commit
 > them.  Tutorials seldom go beyond that.

C'mon, I'm a coauthor of BzrForEmacsDevs, and did my homework (reading
other tutorials).  You should be able to guess that I know better than
that.  But taking your claim at face value: that requires no reading
of manpages to accomplish in git if you've used any VCS (including
RCS) before.  So you're just being contentious here.

You only run into problems by pretending that git is CVS or bzr if you
use facilities like reset (not possible in any other VCS, you have to
revert or commit -- both available in git) and rebase (way beyond your
"the *basic* workflow").

 > >  >   --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.
 > 
 > I was talking about clear documentation, not about the differences
 > between git and bzr.

git documentation is *clear*[1] if you start by understanding how
git's purpose and implementation differs from other VCSes.  It's only
if you try to force it into your preconception of what a (d)VCS should
be that it becomes unclear.  *This is precisely why many people have
trouble grokking Emacs* -- they try to think about it as something
familiar like a wordprocessor or Notepad or a web browser, and when it
violates their preconceptions, they turn away from it in disgust.

 > >  > I want some decent reference documentation.
 > > 
 > > AFAICT, you want your dVCS to be Bazaar.
 > 
 > It doesn't matter what I want in this case, we all know what I will
 > get, right?

Now that Stefan has spoken, yes, I think we do know.  I'm genuinely
sorry for the folks who definitely prefer bzr (of whom Stefan is one,
of course).  It's a damn shame that Shuttleworth pissed off Tom Lord
-- who decided quite early on that the git object data base was the
way to go, and completely rewrote Arch/tla to use it in his
never-published "revc" aka Arch-ng -- and that the Bazaar developers
never came to the conclusion Tom did.

 > Since that's what I will get, I want its documentation to be
 > helpful.

Well, documentation can't help you if you won't help yourself.  Those
who find the git documentation completely unintelligible are going to
have to start by abandoning the idea that git is a poor implementation
of Bazaar.  (Certainly, it is, but that's not helpful in understanding
git or its documentation.)

 > Please don't misrepresent what I wrote by turning it into another
 > "git is more powerful than bzr" thread.  That is not what I was
 > talking about.

Nor is it what I was talking about.  If you want to make suggestions
that will improve git documentation[2], you are going to need to
accept that although overall it sucks, much of it is already written
in an appropriate fashion.  It's possible to discuss whether the word
"index" needs to be mentioned in the brief description of "git
commit"; although the reason for doing so I presented above is valid,
on balance it might not be the best brief description.  But effective
use of git (including understanding what "gurus" are recommending to
get a novice out of a wedge) requires the concepts of "index" and
"commit object".

The fact that bzr doesn't have that concept doesn't mean it's
unnecessary in git documentation, only that people who want git to be
bzr will think it's unnecessary.

 > Anyway, I'm beginning to regret that I answered esr's question.  I
 > should have known what kind of "tide" will be unleashed on me.

Again, you're mistaking what I'm talking about.  I'm also interested
in how to make git's documentation more useful to Emacs devs who don't
like git.

Funding from ORA or not, I'm thinking about taking the git docs and
reorganizing and supplementing them the way Nye et al did for the MIT
X docs.  But if you're going to maintain the attitude that the things
in git that aren't in bzr should be moved to appendices so you don't
need to learn about them, I'm not going to bother continuing to think
about that.

Footnotes: 
[1]  I've already acknowledged the poor organization.

[2]  Maybe Tim O'Reilly will recruit somebody to write the Git Version
Control System Series, or the Git: Essential Reference.