Re: [PATCH v4] documentation: add tutorial for revision walking
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Aug 14, 2019, 19:18 UTC
- Message-ID
- <xmqqd0h75ze8.fsf@gitster-ct.c.googlers.com>
- In-Reply-To
- <20190814183328.GA40797@google.com>
Emily Shaffer <emilyshaffer@google.com> writes:
Show 10 quoted lines
>> > 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).
Show 10 quoted lines
> - 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.