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 <levraiphilippeblain@xxxxxxxxx>
- 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`.
-
Signed-off-by: Philippe Blain <levraiphilippeblain@xxxxxxxxx>
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 <levraiphilippeblain@xxxxxxxxx>
- 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
