Re: [PATCH v4] documentation: add tutorial for revision walking

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

Emily Shaffer <emilyshaffer@google.com> writes:

>> > I think the tutorial itself is pretty much ready...
>> 
>> A few comments after skimming this round; none of them may be a show
>> stopper, but others may have different opinions.
>>  ...
> Hmmm. It sounds like you're saying:
>
> - This object covers walking objects, which is surprising since it's
>   titled about "revision walks". Revision walks are more about commits
>   ("git log").

Yes, the document does not duplicate what existing docs on "revision
walk" API would cover, which is a very good thing, as it is (or at
least "feels to be") primarly about walking objects.

> - Using grep on objects doesn't make any sense.

The grep filter works on commit's log messages, and does not even
look at other types of objects, so while that point is true, what I
was driving at was that skipping commits using grep filter would
mean showing trees and blobs related only to the chosen commits, and
while it can be explained as such (i.e. "trees and blobs contained
only in commits without these strings are excluded"), the practical
usefulness of such a "feature" is dubious (here I am imagining the
primary practical use of "object walk" is to feed pack-objects).

> - Other filters (like pathspecs) which do make sense for object walks
>   aren't covered.

Yup.  For example, "trees and blobs that appear only outside of this
directory hierarchy are excluded" would be useful to enumerate
objects necessary for a narrow commits (again, to feed pack-objects).

> - Apply the grep filter to the commit walk, and apply a more interesting
>   object filter to the object walk.
>
> Or,
>
> - Choose a different kind of filter which is interesting when applied to
>   commits alone _and_ all objects.
>
> In the interest of covering more ground with this kind of tutorial, I'd
> lean more towards the former.

Sorry, I do not have enough imagination to cheer for either of these
two options---these may be "interesting" in the same way as "trees
and blobs contained only in commits without these strings are
excluded" enumeration, but I fail to see practical usefulness
(i.e. the reason why a user may be tempted to learn how to achieve
it).

In any case, that was my personal take and not a strong request to
change anything, as I said upfront.  The document just gave me an
impression that it was teaching coding exercise that may be
interesting but of dubious utility.