On Sun, Jan 07, 2007 at 09:35:11PM -0500, J. Bruce Fields wrote: > chapters 1 and 2: "Read-only" operations: > > clone, fetch, the commit DAG, etc.; material that could be > useful to a linux kernel tester, for example. This also > includes lots of stuff about branch manipulation and fetching, > just because that's necessary to keep a repo up to date and > check out random commits. Once we have "git remote" and > disconnected checkouts most of this could be postponed till > later. I would add a QuickStart Chapter before you start going into the "read-only" oeperations. It would show how to create a completely empty repository, and add a few commits. It would also demonstrate how to clone an example repository (with a fixed set of contents, stored at git://git.kernel.org/pub/scm/git/example and add a commit using "git commit -a". The basic idea is to show the user that git really isn't that hard, *before* you start diving into a lot of details. If you don't tell a user how to make a commit until Chapter 3, he/she will assume it's because it's Really Hard, and you may end up losing them before that. > Chapter 3: "Read-write" operations: > > Read-write stuff: creating commits (basic mention of index), > handling merges, git-gc, ending with distributed stuff: > importing and exporting patches, pull and push, etc. At least some discussions of branches needs to happen here; it's really important to talk about different workflows, and how you use branches as part of your read-write operations. Some folks might or might not use topic branches, but the concept of using temporary branches to try things out is critical. > Chapter 4 (unwritten): interactions with other VCS's > > cvs, subversion. Also some of us use track projects with git > even when all we've got is a sequence of release tarballs to > track, and that might be worth documenting. > > Chapter 6 (unwritten): git internals > > I intend to just do a wholesale import of either tutorial-2.txt, > core-tutorial.txt, or the README, or some combination thereof, > but can't decide which. You might want to consider putting these two chapters into appendices. - 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