From: Theodore Tso <tytso@mit.edu>
Date: Wed, 16 Jul 2008 20:13:33 GMT
Subject: Re: Considering teaching plumbing to users harmful
Message-ID: <20080716201333.GI2167@mit.edu>
In-Reply-To: <32541b130807161135h64024151xc60e23d222a3a508@mail.gmail.com>

On Wed, Jul 16, 2008 at 02:35:16PM -0400, Avery Pennarun wrote:
> In svn, a branch is a revision-controlled directory.  In git, a branch
> is a "ref".  What's a ref?  Well, it's a name for a commit.  What's a
> commit?  Well, it's a blob.  What's a blob?  Err, that's complicated.
> What happens when I delete a branch?  Well, it's still in the reflog.
> What's the reflog?  Well, it's the local revision history of each
> branch.  Local?  Why not shared?  In svn, the revision history of each
> branch is shared, but in git, you don't need to, because...
> 
> Even git branches are surprisingly concept heavy, unless your users
> ask a lot fewer questions than mine.  The really critical question is
> why it's so easy to delete a branch in git, and that leads rapidly
> into the commit-tree stuff, which is always a spiral into plumbing as
> you try to explain the tree of commits.

I don't think you need to go into the plumbing to explain the commit
tree.  What I normally do is tell people that branches point at
commits, and that commits are identified by commit ID's, which can be
full SHA-1 hashes, or which can be abbreviated for convenience's sake.
It's not strictly necessary to tell them about the commit-tree
plumbing command; just that each commit creates a snapshot, and that
commits can have one or more parents, plus the commit mesage, plus the
snapshot.

I do absolutely agree with Johannes' assertion that you don't have to
explain commit-tree, git-rev-list, and all the rest.  The only reason
why users will need to see git-rev-list is because git-log references
it so prominently, and some of the more powerful git-log options are
only documented in git-rev-list.

							- Ted