Re: [DRAFT] Branching and merging with git

[Theodore Tso <tytso@mit.edu>]

On Thu, Nov 16, 2006 at 05:17:01PM -0500, linux@horizon.com wrote:
> I know it took me a while to get used to playing with branches, and I
> still get nervous when doing something creative.  So I've been trying
> to get more comfortable, and wrote the following to document what I've
> learned.
> 
> It's a first draft - I just finished writing it, so there are probably
> some glaring errors - but I thought it might be of interest anyway.

This is really, really good stuff that you've written!  Have you any
thoughts or suggestions about where this text should end up?
Personally, I think this information is actually more important to an
end-user than the current "part two" of the tutorial, which discusses
the object database and the index file.  Perhaps this should be "part
2", and the object database and index file should become "part 3"?  

It might also be a good to consider moving some of the "discussion"
portion the top-level git(7) man page into the object database and
index file discussion.  Right now, the best way to introduce git's
concepts (IMHO), is to start with the part 1 of the tutorial, then go
into the your draft branch/merging with git, then the current part 2
of the tutorial, and then direct folks to read the "discussion"
section of git(7).  Only then do they really have enough background
understanding of the fundamental concepts of git that they won't get
confused when they start talking to other git users, on the git
mailing list, for example.

It would be nice if there was an easy way to direct users through the
documentation in a way which makes good pedagogical sense.  Right now,
one of the reasons why life gets hard for new users is that the
current tutorials aren't enough for them to really undersatnd what's
going on at a conceptual level.  And if users start using "everyday
git" as a crutch, without the right background concepts, the human
brain naturally tries to intuit what's happening in the background,
but without reading the background docs, git is different enough that
they will probably get it wrong, which means more stuff that they have
to unlearn later.  

> * Git's representation of history
> 
> As you recall from Git 101, there are exactly four kinds of objects in
> Git's object database.  All of them have globally unique 40-character hex
> names made by hashing their type and contents.  Blob objects record file
> contents; they contain bytes.  Tree objects record directory contents;
> they contain file names, permissions, and the associated tree or blob
> object names.  Tag objects are shareable pointers to other objects;
> they're generally used to store a digital signature.

Hmm... this assumes that you've read the Git(7) discussion first.
There is enough information here though that maybe you don't need to
say "as you recall".  It might be enough to give a quick summary of
the concepts that are needed to understand the rest of your tutorial,
and then point to git(7) Discussion section for people who need to
learn more details.

> * Remotes files
> 
> Note that branches to fetch are identified by "Pull: " lines in the
> remotes file.  This is another example of the fetch/pull confusion.
> git-pull will be explained eventually.

Maybe we should change git so that a "Fetch: " line in the remotes
file works the same way as "Pull: ", and then recommend that people
use "Fetch: " in order to reduce confusion, as opposed to simply
explaining it away as "yet another example of the histororical
fetch/pull confusion"?

Thanks,