Improve line log documentation

These two patches add more information to the documentation for line history (git log -L) :

* Mention explicitly that only the --patch and --no-patch diff formats are supported
* Mention that parameters <start>, <end> and <funcname> must exist in the starting revision

Regarding point 2 : I stumbled upon this while reading the history of 'filter_refs' in fetch-pack.c. I did

git log -s -L :filter_refs:fetch-pack.c

which shows a list of commits starting with 745f7a8cac (fetch-pack: move core code to libgit.a, 2012-10-26). So then I did

git log -s -L :filter_refs:fetch-pack.c -L :filter_refs:builtin/fetch-pack.c

which fails with

fatal: -L parameter 'filter_refs' starting at line 1: no match

Changes since v1:

* Shorten the commit titles
* Use long options names for --patch and --no-patch
* Remove inexact mention of --function-context
* Reword the clarification regarding <start>, <end> and <funcname> so that it doesn't apply only to regex parameters
* Also add this clarification to Documentation/gitk.txt since it applies there as well

Philippe Blain (2):
doc: log, gitk: document accepted line-log diff formats
doc: log, gitk: line-log arguments must exist in starting revision

 Documentation/git-log.txt | 8 ++++++--
 Documentation/gitk.txt    | 8 ++++++--
 2 files changed, 12 insertions(+), 4 deletions(-)

base-commit: ad05a3d8e5a6a06443836b5e40434262d992889a
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-494%2Fphil-blain%2Fline-log-doc-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-494/phil-blain/line-log-doc-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/494

Range-diff vs v1:

1: 0ed04a8629 ! 1: e68ef0ced3 Documentation/git-log: document accepted line-log diff formats
@@ -1,18 +1,16 @@
Author: Philippe Blain <[email protected]>

- Documentation/git-log: document accepted line-log diff formats
+ doc: log, gitk: document accepted line-log diff formats

Currently the line-log functionality (git log -L) only supports
- displaying patch output (-p, its default behavior) and suppressing it
- (-s). A check was added in the code to that effect in 5314efaea (line-log:
- detect unsupported formats, 2019-03-10) but the documentation was not
+ displaying patch output (-p | --patch, its default behavior) and suppressing it
+ (-s | --no-patch). A check was added in the code to that effect in 5314efaea
+ (line-log: detect unsupported formats, 2019-03-10) but the documentation was not
updated.

Explicitly mention that -L implies -p, that patch output can be suppressed using -s, and that all other diff formats are not allowed.

- Additionnally, mention that the ':<funcname>' form implies --function-context.
-

diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
@@ -24,8 +22,7 @@
give zero or one positive revision arguments.
- You can specify this option more than once.
+ You can specify this option more than once. Implies --patch.
-+ If ``:<funcname>'' is given, implies --function-context.
-+ Patch output can be suppressed using -s, but other diff formats
++ Patch output can be suppressed using --no-patch, but other diff formats
+ (namely --raw, --numstat, --shortstat, --dirstat, --summary,
+ --name-only, --name-status, --check) are not currently implemented.
+
@@ -41,8 +38,7 @@
give zero or one positive revision arguments.
- You can specify this option more than once.
+ You can specify this option more than once. Implies --patch.
-+ If ``:<funcname>'' is given, implies --function-context.
-+ Patch output can be suppressed using -s, but other diff formats
++ Patch output can be suppressed using --no-patch, but other diff formats
+ (namely --raw, --numstat, --shortstat, --dirstat, --summary,
+ --name-only, --name-status, --check) are not currently implemented.
+
2: 4ea4eeae0c ! 2: c7d489794c Documentation/git-log: mention that line-log regex must match in starting revision
@@ -1,10 +1,10 @@
Author: Philippe Blain <[email protected]>

- Documentation/git-log: mention that line-log regex must match in starting revision
+ doc: log, gitk: line-log arguments must exist in starting revision

- When giving a regex as parameter <start> or <end> in
- git log -L <start>,<end>:<file>, or a function name in
- git log -L :<funcname>:<file>, the given regex must match in the starting
+ The line number, regex or offset parameters <start> and <end> in
+ git log -L <start>,<end>:<file>, or the function name regex in
+ git log -L :<funcname>:<file> must exist in the starting
revision, or else the command exits with a fatal error.

This is not obvious in the documentation, so add a note to that
@@ -20,8 +20,22 @@
not give any pathspec limiters. This is currently limited to a walk starting from a single revision, i.e., you may only
- give zero or one positive revision arguments.
-+ give zero or one positive revision arguments, and any given regex for
-+ <start> or <end> (or <funcname>) must match in the starting revision.
++ give zero or one positive revision arguments, and
++ <start> and <end> (or <funcname>) must exist in the starting revision.
You can specify this option more than once. Implies --patch.
- If ``:<funcname>'' is given, implies --function-context.
- Patch output can be suppressed using -s, but other diff formats
+ Patch output can be suppressed using --no-patch, but other diff formats
+ (namely --raw, --numstat, --shortstat, --dirstat, --summary,
+
+ diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
+ --- a/Documentation/gitk.txt
+ +++ b/Documentation/gitk.txt
+@@
+ (or the function name regex <funcname>) within the <file>. You may
+ not give any pathspec limiters. This is currently limited to
+ a walk starting from a single revision, i.e., you may only
+- give zero or one positive revision arguments.
++ give zero or one positive revision arguments, and
++ <start> and <end> (or <funcname>) must exist in the starting revision.
+ You can specify this option more than once. Implies --patch.
+ Patch output can be suppressed using --no-patch, but other diff formats
+ (namely --raw, --numstat, --shortstat, --dirstat, --summary,

gitgitgadget