Subject: Re: Long names for `git log -S` and `git log -G`

From: Junio C Hamano <[email-masked]>
Date: Tue, 19 Nov 2024 12:52:50 +0900

Illia Bobyr <[email-masked]> writes:

> Also,`diffcore` docs says:
>
>> "-G<regular-expression>" (mnemonic: grep)
>
> I was thinking of `--pickaxe` for `-S` and `--grep` for `-G`.

In the context of "git diff", calling "-G" "--grep" would be OK, but
in the context of "git log", there is "--grep" already, so that
won't fly.

> `--pickaxe-grep` for `-G` seems like a reasonable alternative name for `-G`.

That is probably OK (even though "-G" is not exactly what the
pickaxe machinery wants to do; "--grep-in-patch" might be closer to
the intent).

> Not sure what would be a reasonably short alternative for `-S`.
> `--pickaxe-occurance-change` seems too long, and might not be as clear.
> `--pickaxe-occurance-count-change` is just way too long.

Giving a tool a meaningful name is an excellent idea.  If the
meaningful name guides users to the right way to use the tool,
it would be ideal.  Which means that to name it right, you'd need to
know what it exactly is for.

The -S feature was written to become one of the building blocks of
Linus's "clearly superior algorithm", described in [1].  Linus talks
about "where did this _line_ come from?", but the algorithm is more
generally about a block of code.  The expected use case is for -S to
be fed sufficiently unique block of text so that we can efficiently
detect the transition of occurence count from 1 (because wee start
from sufficiently unique block of code) down to 0 (which is the
boundary in history where the block of code was first introduced in
its current form).  It detects any occurence count change, but its
primary focus is to find a transition from 1 to 0 (when going
backwards in history).  Its spirit is more about "finding where it
appeared in its current shape".

[Footnote]

*1* https://lore.kernel.org/git/[email-masked]/