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

From: Ramkumar Ramachandra <artagnon@gmail.com>
Date: May 31, 2013, 12:04 UTC
Message-ID: <CALkWK0m+kUa0QUotHXSYK40vFviFFv2yETnf6sEZMh05gOgLKg@mail.gmail.com>
In-Reply-To: <7v38tcb7yx.fsf@alter.siamese.dyndns.org>

Junio C Hamano wrote:

> [...]

I agree with everything else, and made changes accordingly.

>         This transformation limits the set of filepairs to those
>         that change specified strings between the preimage and the
>         postimage in a certain way.

Definitely good.

>         -S<block of text> and -G<regex> options are used to specify
>         different ways these strings are sought.

Definitely better than the "two kinds of pickaxe" thing.

Show 5 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?

When `-S` or `-G` are used without `--pickaxe-all`, only filepairs that match their respective criterion are kept in the output. When `--pickaxe-all` is used, if even one filepair matches their respective criterion in a changeset, the entire changeset is kept. This behavior is designed to make reviewing changes in the context of the whole changeset easier.

Show 9 quoted lines

> I am not sure why it is necessary to say anything about what the
> previous step (diffcore-rename) might have done.  The input of this
> (or any other) step in the diffcore pipeline is a preimage-postimage
> filepairs, and to this transformation the filename does not matter.
> Whether a file was moved (either "wholesale", implying nothing
> changed, or renamed with modification at the same time) without
> touching the block of text, or a file did not get involved in any
> renaming, the only thing that matters is what the preimage and the
> postimage in a filepair has (or does not have).

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?

I did do a s/rename detection/diffcore-rename/ though, so the user knows where to look for more on this rename thing.