Re: Yet another Git tutorial

On Monday 28 April 2008, John Wiegley wrote:

Some comments after a quick read-through:

(in general) In you examples, you are using the "git foo" notation, while you're using the "git-foo" notation when referring to git commands elsewhere in the text. This is probably OK; just be aware that the dashed form of the commands will disappear in a future git version.

(in general II) You mention "git prune" a couple of places. I think "git gc" is the command we encourage new users to use, so you might want to use that instead.

(p.2 (and p.19-20)) I think most people say "index" and not "index cache". In the git codebase, "index" and "cache" are often confused (I think Linus initially named it "cache"), but I think from a user perspective, we try to use the term "index".

(p.3) In the simple diagram, you show the 'checkout' activity as an arrow directly from 'Repository' to 'Working Tree'. What actually happens on checkout is copying the appropriate tree object into the index, and then applying the index onto the working tree. IOW if you want to be 100% correct the checkout arrow should go through the index. But this is only a minor issue; if you feel understanding is better conveyed by the existing diagram, please don't change.

(p.9) "But if I pass the -f flag to git-checkout, it becomes identical to git-reset --hard": In the context of the command above (resetting the working tree to 5f1bc85) there are in fact no difference between the two commands. However, in general, there is one crucial difference between "git reset --hard" and "git checkout -f": "git reset --hard" will rewrite which commit the current branch points at, whereas "git checkout -f" will not. (I see you treat this later in "To reset, or not to reset", but I think it should be fixed on p.9 as well.)

(p.10) In the diagram at the top, the arrow from the root tree object to HEAD commit is labelled "parent". I think this label rather belongs on the arrow from the HEAD commit to its parent.

(p.11) "name~10" Just to make things perfectly clear, I would state that "name~10" is equivalent to "name^^^^^^^^^^".

(p.11-12) This entire list is prefixed with "nam[ing] commits - and ranges of commits", so in a strict sense "name:file" and "name{tree}" does not belong here. But you have to put them somewhere...

(p.15) "Even the transformation from X to W is changed": I think this should be the other way around: "W to X".

(p.16) "For every commit this that involves conflicts": s/ this//? Also, in the preceding sentence, I'd prefer "...to its (now rewritten) parent commit" instead of the current "...to its (now) rewritten parent commit".

Otherwise, I think it's informative and well-written. Nice work.

Have fun! :)

...Johan