Re: [PATCH] Add a birdview-on-the-source-code section to the user manual

[Junio C Hamano <junkio@cox.net>]

"J. Bruce Fields" <bfields@fieldses.org> writes:

> The organization of the next bit is slightly confusing: we're set up to
> expect a longer lecture on the revision walker, but instead there's just
> the historical note on git-rev-list, a mention of 'revision.c',
> 'revision.h', and 'struct rev_info', and then it rapidly digresses into
> discussing builtins.

I had the same impression.

I was meaning to write a "code walkthru for git hackers and
wannabes" with target audience quite different from the
user-manual.  My idea of which areas to cover in what order
seems to match with what Johannes started.

 - sha1_name.c;

 - read_sha1_file();

 - revision.c::setup_revisions() to talk about parsing but not
   about walking yet.

 - start from builtin-merge-base.c into commit.c to talk about
   revision traversal done by get_merge_bases().  This codepath
   is much simpler than the revision.c machinery and is a good
   primer to understand the latter.

 - builtin-diff-tree.c to show one tree and two tree cases, go
   into log-tree.c then tree-diff.c to show the use of
   add_remove() and change() callbacks, and then finally talk
   about diff_flush(), without talking about diffcore
   transformations yet.

 - start from builtin-log.c to review the setup_revisions(),
   then talk about prepare_revision_walk() and get_revision()
   machinery, first pass without talking about path limiting and
   then with path limiting.

 - fetch-pack.c and upload-pack.c to talk about the native
   protocol over ssh and local forking, how revision traversal
   machinery is used, the "objects pointed by refs are complete"
   contract.

 - daemon.c to see how upload-pack is invoked.

 - read_cache(), active_cache[], active_nr and friends;

 - update-index and write-tree, including how cache-tree
   optimizes tree writing after small updates.  Advanced students
   can also look at git-apply here.

 - unpack-trees.c and builtin-read-tree.c to talk about index stages.

 - diffcore transformations, especially diffcore-rename.

 - merge-recursive