Long argument names are easier to read, compared to short ones. So
while short arguments are great when you want to type a command quickly,
the documentation readability is improved if we use long argument names.
Note for reviewers: All changes are just a replacement of `-G` with
`--patch-grep` and `-S` with `--patch-modifies`. But as the text was
reformatted to fit the same width in a few places it might look like
there are more changes, if the diff is only line-wise and not word-wise.
The only an exception are changes in `gitdiffcore.adoc`, where I did
rephrase a sentence. I've moved introduction of the short versions of
the `--patch-{grep,modifies}` into a subsequent paragraph. The reason
is that I wanted to keep a note on the `-G` mnemonic, and it was awkward
if I would repeat the short definition twice over a span of two
paragraphs.
---
Documentation/diff-options.txt | 34 ++++++++++-----------
Documentation/git-blame.txt | 2 +-
Documentation/gitdiffcore.txt | 55 +++++++++++++++++-----------------
3 files changed, 46 insertions(+), 45 deletions(-)
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 07413d..c9f7c 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -658,8 +658,8 @@ renamed entries cannot appear if detection for those types is disabled.
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.
+block in the preimage back into `--patch-modifies`, and keep going until
+you get the very first version of the block.
+
Binary files are searched as well.
@@ -668,9 +668,9 @@ Binary files are searched as well.
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:
+To illustrate the difference between `--patch-modifies=<regex>
+--pickaxe-regex` and `--patch-grep=<regex>`, consider a commit with the
+following diff in the same file:
+
----
+ return frotz(nitfol, two->ptr, 1, 0);
@@ -678,9 +678,9 @@ file:
- hit = frotz(nitfol, mf2.ptr, 1, 0);
----
+
-While `git log -G"frotz\(nitfol"` will show this commit, `git log
--S"frotz\(nitfol" --pickaxe-regex` will not (because the number of
-occurrences of that string did not change).
+While `git log --patch-grep="frotz\(nitfol"` will show this commit, `git
+log --patch-modifies="frotz\(nitfol" --pickaxe-regex` will not (because the
+number of occurrences of that string did not change).
+
Unless `--text` is supplied patches of binary files without a textconv
filter will be ignored.
@@ -689,22 +689,22 @@ See the 'pickaxe' entry in linkgit:gitdiffcore[7] for more
information.
`--find-object=<object-id>`::
- Look for differences that change the number of occurrences of
- the specified object. Similar to `-S`, just the argument is different
- in that it doesn't search for a specific string but for a specific
- object id.
+ Look for differences that change the number of occurrences of the
+ specified object. Similar to `--patch-modifies`, just the argument
+ is different in that it doesn't search for a specific string but
+ for a specific object id.
+
The object can be a blob or a submodule commit. It implies the `-t` option in
`git-log` to also find trees.
`--pickaxe-all`::
- When `-S` or `-G` finds a change, show all the changes in that
- changeset, not just the files that contain the change
- in _<string>_.
+ When `--patch-modifies` or `--patch-grep` finds a change, show all
+ the changes in that changeset, not just the files that contain the
+ change in _<string>_.
`--pickaxe-regex`::
- Treat the _<string>_ given to `-S` as an extended POSIX regular
- expression to match.
+ Treat the _<string>_ given to `--patch-modifies` as an extended
+ POSIX regular expression to match.
endif::git-format-patch[]
diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index b1d7fb..0f21d3 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -41,7 +41,7 @@ a text string in the diff. A small example of the pickaxe interface
that searches for `blame_usage`:
-----------------------------------------------------------------------------
-$ git log --pretty=oneline -S'blame_usage'
+$ git log --pretty=oneline --patch-modifies='blame_usage'
5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <ancestry-file>
ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output
-----------------------------------------------------------------------------
diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt
index e934b9..e7f98 100644
--- a/Documentation/gitdiffcore.txt
+++ b/Documentation/gitdiffcore.txt
@@ -245,33 +245,34 @@ diffcore-pickaxe: For Detecting Addition/Deletion of Specified String
This transformation limits the set of filepairs to those that change
specified strings between the preimage and the postimage in a certain
-way. `--patch-modifies=<string>` (`-S<string>` for short) and
-`--patch-grep=<regex>` (`-G<regex>` for short) are used to specify
-different ways these strings are sought.
-
-`-S<string>` detects filepairs whose preimage and postimage
-have different number of occurrences of the specified _<string>_.
-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 _<string>_ as an extended POSIX regular expression to match,
-instead of a literal string.
-
-`-G<regex>` (mnemonic: grep) detects filepairs whose textual diff has
-an added or a deleted line that matches the given _<regex>_. 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. To speed things up,
-binary files without textconv filters will be ignored.
-
-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.
+way. `--patch-modifies=<string>` and `--patch-grep=<regex>` are used
+to specify different ways these strings are sought.
+
+`--patch-modifies=<string>` (`-S<string>` for short) detects filepairs
+whose preimage and postimage have different number of occurrences of
+the specified _<string>_. 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 `--patch-modifies` 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 _<string>_ as
+an extended POSIX regular expression to match, instead of a literal
+string.
+
+`--patch-grep=<regex>` (`-G<regex>` for short, 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. To speed things up, binary files without
+textconv filters will be ignored.
+
+When `--patch-modifies` or `--patch-grep` 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
---------------------------------------------------------
--
2.45.2
