I was initially somewhat dissapointed that a posting marked as RFC did not contain a draft that is commentable, but we would probably want to know how the updated document set will be organized in general first. There was a discussion both here and on #irc, while Pasky and gang were working on the wiki, about sprucing up the introductory documentation set.
The core-tutorial grow out of a short tutorial to start from Plumbing basics (what's in object store) to cover Porcelainish; when it was written there was not another user-level document, so it had to cover both, but it is probably a good idea to move the parts that talk about Porcelainish to other documents and make it "A short tutorial on git Plumbing" document. Maybe we can have a tiered document set like this:
- Your first experience with git with walkthru. This shows the
minimum basic operations to get started a stand-alone "hello
world" project, without talking about index nor object store.
The current tutorial.txt is probably good enough with
updates.
- Understanding git as an end user. Currently, this is
included in the global map git(7) documentation. It might
make sense to separate it out. This should talk about
concepts like blobs/trees/commits/trust/index without going
into lowlevel details of the implementation. The stress
should be on what they are for, not operationally but
philosophically. What's currently in README would be
suitable for this part, with some additional topics:
- branches. "Tying it all together" section talks about the
single branch and "the HEAD state"; we should talk about
why you would want to use multiple branches (either
keeping track of your own development, or keeping track of
somebody else's) and stress branches are to keep separate
things separate (explained that way it becomes clear why
you should not commit on a remote tracking branch). - ancestry traversal. what "A..B" or "^A ^B C" means and why
you would want to say them. - Everyday.
- Special interests: cvs migration, howto/ documents.
- The global map git(7) with pointers to individual commands,
and the glossary.
- Tutorial on Plumbing.
For a new end-user, the order to read would be from the top to bottom. "Everyday" should cover most of what are needed for different classes of users, and other things can be looked up from the global map.
I think tutorial.txt is the right "your first experience with git with walkthru" document, and the materials it gives, and the order in which it introduces them, are very well thought out; kudos to JBF. We might also want to show "git grep", but other than that I do not think of anything that a new user might want to use on the first day.
It is deliberately sketchy at times to keep the flow of walkthru clean and simple, and I'd like to keep it that way. I would however like to see the examples to show the expected output from the commands, like the initial part of the current core-tutorial.txt does. Also, I'd like to see a "see also" link to each step that refers the user to "what if this step does not work as expected for you", either separate document or a section in the appendix part of the same document, without cluttering the main text too much.
Some commands and syntax it mentions may need to be rethought in the light what happened recently, especially the internal version of diff and log/show/whatchanged unification that happened before the 1.3.0 came out.
* "git diff A B" should probably be spelled as "git diff A..B"
throughout for consistency.
* Today's "git log" is more powerful than the one we had when
the tutorial was first written, and we probably want to
recommend "git log [-p|--stat]" in place of whatchanged;
whatchanged is kept primarily for historical reasons and to
give a different default output format than log. A new user
does not have to even know about it.
Then reorganize the initial part core-tutorial.txt to match the examples tutorial.txt gives, and demonstrate what is happening under the hood. The tutorial says "git init-db" then "git add". The core-tutorial would match that and explain what happens when "git init-db" is run (creates .git/objects etc.) and "git add" is run (populates the index).
Jakub Narebski
