[PATCH v5 10/10] diff: docs: Use --patch-{grep,modifies} over -G/-S

[Illia Bobyr <illia.bobyr@gmail.com>]

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