Re: Git Community Book

From: Daniel Barkalow <barkalow@iabervon.org>
Date: Jul 29, 2008, 22:34 UTC
Message-ID: <alpine.LNX.1.00.0807291716460.19665@iabervon.org>
In-Reply-To: <d411cc4a0807290920p62f5d7e1r727a62ef2b4611fc@mail.gmail.com>

On Tue, 29 Jul 2008, Scott Chacon wrote:

Show 7 quoted lines

> So I wanted to develop a really nice, easy to follow book for Git
> newcomers to learn git quickly and easily.  One of the issues I
> remember having when learning Git is that there is a lot of great
> material in the User Guide, Tutorial, Tutorial 2, Everyday Git, etc -
> but they're all huge long documents that are sometimes difficult to
> come back to and remember where you were, and I didn't know which one
> to start with or where to find what I was looking for, etc.

It would be good to include stuff from http://eagain.net/articles/git-for-computer-scientists/

Maybe only in inspiration, since it doesn't have an obvious license and it's stylisticly more technical. But it would be nice to have diagrams of "this is what git thinks of as history", possibly even arranging them like gitk shows things (older downward, refs pointing in from the side).

In particular, I think it's really useful to show a commit graph with branching and merging, and introduce refs as movable pointers to commits in the graph, and local branches as refs that you move and tracking refs as refs that copy values in other repositories.

I think you can even gloss of details of blobs and trees because they pretty much work just like files and directories in a filesystem (except that they take up much less storage in large quantities than you'd think). The only potentially interesting things are (1) a blob names the inode, not the dentry, so it's the file contents, not the name, mode, etc; and (2) the permission bits are just 'x', we've got symlinks, there are no owner/group or other attributes and "see also Submodules".

But I think that the section:
  http://eagain.net/articles/git-for-computer-scientists/#history
should have an equivalent in any git documentation that can have diagrams, 
and introducing a history diagram style early means that you can do a 
bunch of simple pictures to explain operations like "git checkout -b foo" 
or "git reset --hard HEAD^^" or "git checkout origin/master".

	-Daniel
*This .sig left intentionally blank*