On Thu, Nov 16, 2006 at 05:17:01PM -0500, linux@xxxxxxxxxxx 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, - Ted - To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html