[v2,0/2] Improve line log documentation

Message

Koji Nakamaru via GitGitGadget Dec. 26, 2019, 5:43 p.m. UTC

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 <[e-mail]>
      
     -    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 <[e-mail]>
      
       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 <[e-mail]>
      
     -    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`,