Subject: Re: [PATCH v5] documentation: add tutorial for object walking

From: Emily Shaffer <[email-masked]>
Date: Fri, 11 Oct 2019 16:26:33 -0700

On Fri, Oct 11, 2019 at 02:50:34PM +0900, Junio C Hamano wrote:
> Emily Shaffer <[email-masked]> writes:
> 
> > @@ -77,6 +77,7 @@ API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technica
> >  SP_ARTICLES += $(API_DOCS)
> >  
> >  TECH_DOCS += MyFirstContribution
> > +TECH_DOCS += MyFirstRevWalk
> 
> s/Rev/Object/ probably (if so I can locally amend).
Yes, that's the case, although I'll send a reroll shortly if you don't
want to amend locally - there's other stuff to fix according to you and
SZEDER.

> 
> > diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt
> > new file mode 100644
> > index 0000000000..7085f17072
> > --- /dev/null
> > +++ b/Documentation/MyFirstObjectWalk.txt
> > @@ -0,0 +1,905 @@
> > +My First Object Walk
> > +======================
> > +
> > +== What's an Object Walk?
> > +
> > +The object walk is a key concept in Git - this is the process that underpins
> > +operations like `git log`, `git blame`, and `git reflog`. Beginning at HEAD, the
> > +list of objects is found by walking parent relationships between objects.
> 
> The above is more about revision walk, for which we have plenty of
> docs already, isn't it?  Walking objects, while walking the commit
> DAG, is a lessor concept than the key "revision walk" concept and
> underpins different set of operations like object transfer and fsck.
> 
> Also, the object walk, unlike the revision walk, follows containment
> relationships between objects.

Good point; I'll rewrite this paragraph rather than trying to just edit
it a little for the next reroll.

> 
> > +A related concept is the revision walk, which is focused on commit objects and
> > +their relationships.
> 
> Yes, s/their/& parent/ perhaps, to contrast the two a bit better.
> `git log` and friends, if they need to be listed, should come on
> this side, I think.
> 
OK.