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

[Ramkumar Ramachandra <artagnon@gmail.com>]

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.

>         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.

> 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.