diffcore-pickaxe doc: document -S and -G properly
The documentation of -S and -G is very sketchy. Completely rewrite the sections in Documentation/diff-options.txt and Documentation/gitdiffcore.txt. References:52e9578([PATCH] Introducing software archaeologist's tool "pickaxe".)f506b8e(git log/diff: add -G<regexp> that greps in the patch text) Inputs-from: Phil Hord <phil.hord@gmail.com> Co-authored-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Ramkumar Ramachandra
Junio C Hamano
parent
276b22d333
commit
5bc3f0b567
@ -383,14 +383,36 @@ ifndef::git-format-patch[]
|
||||
that matches other criteria, nothing is selected.
|
||||
|
||||
-S<string>::
|
||||
Look for differences that introduce or remove an instance of
|
||||
<string>. Note that this is different than the string simply
|
||||
appearing in diff output; see the 'pickaxe' entry in
|
||||
linkgit:gitdiffcore[7] for more details.
|
||||
Look for differences that change the number of occurrences of
|
||||
the specified string (i.e. addition/deletion) in a file.
|
||||
Intended for the scripter's use.
|
||||
+
|
||||
It is useful when you're looking for an exact block of code (like a
|
||||
struct), and want to know the history of that block since it first
|
||||
came into being: use the feature iteratively to feed the interesting
|
||||
block in the preimage back into `-S`, and keep going until you get the
|
||||
very first version of the block.
|
||||
|
||||
-G<regex>::
|
||||
Look for differences whose added or removed line matches
|
||||
the given <regex>.
|
||||
Look for differences whose patch text contains added/removed
|
||||
lines that match <regex>.
|
||||
+
|
||||
To illustrate the difference between `-S<regex> --pickaxe-regex` and
|
||||
`-G<regex>`, consider a commit with the following diff in the same
|
||||
file:
|
||||
+
|
||||
----
|
||||
+ return !regexec(regexp, two->ptr, 1, ®match, 0);
|
||||
...
|
||||
- hit = !regexec(regexp, mf2.ptr, 1, ®match, 0);
|
||||
----
|
||||
+
|
||||
While `git log -G"regexec\(regexp"` will show this commit, `git log
|
||||
-S"regexec\(regexp" --pickaxe-regex` will not (because the number of
|
||||
occurrences of that string did not change).
|
||||
+
|
||||
See the 'pickaxe' entry in linkgit:gitdiffcore[7] for more
|
||||
information.
|
||||
|
||||
--pickaxe-all::
|
||||
When `-S` or `-G` finds a change, show all the changes in that
|
||||
@ -398,8 +420,8 @@ ifndef::git-format-patch[]
|
||||
in <string>.
|
||||
|
||||
--pickaxe-regex::
|
||||
Make the <string> not a plain string but an extended POSIX
|
||||
regex to match.
|
||||
Treat the <string> given to `-S` as an extended POSIX regular
|
||||
expression to match.
|
||||
endif::git-format-patch[]
|
||||
|
||||
-O<orderfile>::
|
||||
|
||||
@ -222,26 +222,35 @@ version prefixed with '+'.
|
||||
diffcore-pickaxe: For Detecting Addition/Deletion of Specified String
|
||||
---------------------------------------------------------------------
|
||||
|
||||
This transformation is used to find filepairs that represent
|
||||
changes that touch a specified string, and is controlled by the
|
||||
-S option and the `--pickaxe-all` option to the 'git diff-*'
|
||||
commands.
|
||||
This transformation limits the set of filepairs to those that change
|
||||
specified strings between the preimage and the postimage in a certain
|
||||
way. -S<block of text> and -G<regular expression> options are used to
|
||||
specify different ways these strings are sought.
|
||||
|
||||
When diffcore-pickaxe is in use, it checks if there are
|
||||
filepairs whose "result" side and whose "origin" side have
|
||||
different number of specified string. Such a filepair represents
|
||||
"the string appeared in this changeset". It also checks for the
|
||||
opposite case that loses the specified string.
|
||||
"-S<block of text>" detects filepairs whose preimage and postimage
|
||||
have different number of occurrences of the specified block of text.
|
||||
By definition, it will not detect in-file moves. Also, when a
|
||||
changeset moves a file wholesale without affecting the interesting
|
||||
string, diffcore-rename kicks in as usual, and `-S` omits the filepair
|
||||
(since the number of occurrences of that string didn't change in that
|
||||
rename-detected filepair). When used with `--pickaxe-regex`, treat
|
||||
the <block of text> as an extended POSIX regular expression to match,
|
||||
instead of a literal string.
|
||||
|
||||
When `--pickaxe-all` is not in effect, diffcore-pickaxe leaves
|
||||
only such filepairs that touch the specified string in its
|
||||
output. When `--pickaxe-all` is used, diffcore-pickaxe leaves all
|
||||
filepairs intact if there is such a filepair, or makes the
|
||||
output empty otherwise. The latter behaviour is designed to
|
||||
make reviewing of the changes in the context of the whole
|
||||
"-G<regular expression>" (mnemonic: grep) detects filepairs whose
|
||||
textual diff has an added or a deleted line that matches the given
|
||||
regular expression. This means that it will detect in-file (or what
|
||||
rename-detection considers the same file) moves, which is noise. The
|
||||
implementation runs diff twice and greps, and this can be quite
|
||||
expensive.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
diffcore-order: For Sorting the Output Based on Filenames
|
||||
---------------------------------------------------------
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user