Re: Git Community Book

[Junio C Hamano <gitster@pobox.com>]

Junio C Hamano <gitster@pobox.com> writes:

> "Scott Chacon" <schacon@gmail.com> writes:
>
>> 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.
>
> Interesting.  A few comments, before I get dragged into my day job fully.

(cont'd)

I was planning to comment on the contents (i.e. text) but it appears that
most of the stuff was borrowed from the User Manual, so I won't.

	Side note: I wonder if this makes the whole "Community Book"
	GPLv2.  What would happen to the part that includes your own
	screencast?  You do not mind it be contaminated by our licence?

But there seems to be some stuff User Manual does not talk about.

[3_basic_branching_and_merging.html]

 - You've talked about low-level individual objects in an earlier section
   but you stopped at showing a single commit pointing at a tree.  People
   would find branching and merging very hard to get, without
   understanding the commit DAG.  On the other hand, you can explain
   commit DAG without going into details down to trees and blobs in the
   earlier section.  The user manual has "understanding reachability"
   section early on for this exact reason.

[5_creating_new_empty_branches.html]

 - As I repeatedly said on the list, I do not think teaching this is
   useful.  Multiple roots may happen as a result of pushing (or pulling)
   from a repository with unrelated root, but it is not something you
   would want to actively aim for.  At least there needs an explanation
   for the reason why making disjoint roots in the same repository is
   (sometimes) a good thing to do, and what its downsides are.