Re: [PATCH 2/2] diffcore-pickaxe doc: document -S and -G properly

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 2, 2013, 19:56 UTC
Message-ID: <7v7gicnv6o.fsf@alter.siamese.dyndns.org>
In-Reply-To: <CALkWK0m+kUa0QUotHXSYK40vFviFFv2yETnf6sEZMh05gOgLKg@mail.gmail.com>

Ramkumar Ramachandra <artagnon@gmail.com> writes:

Show 8 quoted lines

>>         Without
>>         --pickaxe-all, only the filepairs matching the given
>>         criterion is left in the output; all filepairs are left in
>>         the output when --pickaxe-all is used and if at least one
>>         filepair matches the given criterion.
>
> Why do a poor-man's version of --pickaxe-all here, when the last
> paragraph already does justice to this?

The point of the first paragraph is to serve to help both:

 (1) people who read about this rather technical part of the
     diffcore pipeline machinery, to prepare them by listing what
     they will learn about in the section; and

 (2) those who already have read and want to skim over, by giving a
     concise summary.

It may have been "poor" because it was merely "something like this" patch, though.

Show 7 quoted lines

> While what you're saying is technically true, I think it is important
> to explain the interaction between diffcore-pickaxe and
> diffcore-rename as I have done.  Someone who wants to understand what
> `git log -S` does will come to this page and read this section:
> without reading diffcore-rename, she will have an incomplete picture;
> what's the harm in explaining diffcore-rename in the context of
> diffcore-pickaxe?

That is a red-herring; that is exactly why we upfront say that the diffcore machinery is a pipeline and we describe upstream processing like rename before we talk about pickaxe in the same document.

This document is the most accurate _technical_ documentation of how the pipeline works (and it is not in section 1 of the manual set). If you want to improve end-user documentation by adding explanation for interactions between pipeline stages and also pathspec, I am all for it, but I think that belongs to the larger "git help diff", not "git help diffcore".