diff mbox series

[1/2] Documentation/git-log: document accepted line-log diff formats

Message ID 0ed04a8629a64d15062e13c1f1739b01436a897b.1576559263.git.gitgitgadget@gmail.com (mailing list archive)
State New, archived
Headers show
Series Improve line log documentation | expand

Commit Message

Johannes Schindelin via GitGitGadget Dec. 17, 2019, 5:07 a.m. UTC 
From: Philippe Blain <levraiphilippeblain@gmail.com>

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
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@gmail.com>
---
 Documentation/git-log.txt | 6 +++++-
 Documentation/gitk.txt    | 6 +++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

Comments

SZEDER Gábor Dec. 17, 2019, 11:33 a.m. UTC | #1 
On Tue, Dec 17, 2019 at 05:07:42AM +0000, Philippe Blain via GitGitGadget wrote:
> From: Philippe Blain <levraiphilippeblain@gmail.com>
> 
> 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
> 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@gmail.com>
> ---
>  Documentation/git-log.txt | 6 +++++-
>  Documentation/gitk.txt    | 6 +++++-
>  2 files changed, 10 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
> index b406bc4c48..1c52bf184d 100644
> --- a/Documentation/git-log.txt
> +++ b/Documentation/git-log.txt
> @@ -77,7 +77,11 @@ produced by `--stat`, etc.
>  	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.
> -	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`.

':<funcname>' doesn't imply '--function-context', but defines a line
range starting at the function-name-looking line that first matches
"funcname" and ending just before the next function-name-looking line,
and line-log will then show that line range as context for each
commit.  Although in many cases it shows diffs that look like as if
'--function-context' were given, there are corner cases where they
clearly differ, e.g. when following the history of a function that was
at one point combined with the function directly below it.

Note the two commits in the middle that show two functions although
only one of them was actually modified in each of those commits:

  $ git log --oneline -L:func:file.c
  04b0c16 Combine funcA() and funcB() into func()
  
  diff --git a/file.c b/file.c
  --- a/file.c
  +++ b/file.c
  @@ -1,9 +1,4 @@
  -int funcA()
  +int func()
   {
  -	return A;
  -}
  -
  -int funcB()
  -{
  -	return B;
  +	return A + B;
   }
  ed0d4d9 Modify funcB()
  
  diff --git a/file.c b/file.c
  --- a/file.c
  +++ b/file.c
  @@ -1,9 +1,9 @@
   int funcA()
   {
   	return A;
   }
   
   int funcB()
   {
  -	return b;
  +	return B;
   }
  0d4e9b5 Modify funcA()
  
  diff --git a/file.c b/file.c
  --- a/file.c
  +++ b/file.c
  @@ -1,9 +1,9 @@
   int funcA()
   {
  -	return a;
  +	return A;
   }
   
   int funcB()
   {
   	return b;
   }
  c3f8a44 Add funcA() and funcB()
  
  diff --git a/file.c b/file.c
  --- /dev/null
  +++ b/file.c
  @@ -0,0 +1,9 @@
  +int funcA()
  +{
  +	return a;
  +}
  +
  +int funcB()
  +{
  +	return b;
  +}

Now compare that to the same two middle commits shown with '-p
--function-context', which doesn't show the unmodified function:

  $ git log --oneline -p --function-context file.c
  04b0c16 Combine funcA() and funcB() into func()
  diff --git a/file.c b/file.c
  index 89571b3..33301ea 100644
  --- a/file.c
  +++ b/file.c
  @@ -1,9 +1,4 @@
  -int funcA()
  +int func()
   {
  -	return A;
  -}
  -
  -int funcB()
  -{
  -	return B;
  +	return A + B;
   }
  ed0d4d9 Modify funcB()
  diff --git a/file.c b/file.c
  index 13592c8..89571b3 100644
  --- a/file.c
  +++ b/file.c
  @@ -5,5 +5,5 @@ int funcA()
   
   int funcB()
   {
  -	return b;
  +	return B;
   }
  0d4e9b5 Modify funcA()
  diff --git a/file.c b/file.c
  index 11e1e87..13592c8 100644
  --- a/file.c
  +++ b/file.c
  @@ -1,6 +1,6 @@
   int funcA()
   {
  -	return a;
  +	return A;
   }
   
   int funcB()
  c3f8a44 Add funcA() and funcB()
  diff --git a/file.c b/file.c
  new file mode 100644
  index 0000000..11e1e87
  --- /dev/null
  +++ b/file.c
  @@ -0,0 +1,9 @@
  +int funcA()
  +{
  +	return a;
  +}
  +
  +int funcB()
  +{
  +	return b;
  +}
Derrick Stolee Dec. 17, 2019, 3:33 p.m. UTC | #2 
On 12/17/2019 12:07 AM, Philippe Blain via GitGitGadget wrote:
> From: Philippe Blain <levraiphilippeblain@gmail.com>
> 
> 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
> 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`.

s/Additionnally/Additionally/

> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
> ---
>  Documentation/git-log.txt | 6 +++++-
>  Documentation/gitk.txt    | 6 +++++-
>  2 files changed, 10 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
> index b406bc4c48..1c52bf184d 100644
> --- a/Documentation/git-log.txt
> +++ b/Documentation/git-log.txt
> @@ -77,7 +77,11 @@ produced by `--stat`, etc.
>  	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.
> -	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

I would prefer the longer "--no-patch" over "-s", especially because you
follow with several options in this style.

> +	(namely `--raw`, `--numstat`, `--shortstat`, `--dirstat`, `--summary`,
> +	`--name-only`, `--name-status`, `--check`) are not currently implemented.
>  +
>  include::line-range-format.txt[]
>  
> diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
> index 1eabb0aaf3..91993b9d4c 100644
> --- a/Documentation/gitk.txt
> +++ b/Documentation/gitk.txt
> @@ -106,7 +106,11 @@ linkgit:git-rev-list[1] for a complete list.
>  	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.
> -	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

(same)

> +	(namely `--raw`, `--numstat`, `--shortstat`, `--dirstat`, `--summary`,
> +	`--name-only`, `--name-status`, `--check`) are not currently implemented.

Thanks,
-Stolee
Philippe Blain Dec. 18, 2019, 2:44 a.m. UTC | #3 
That’s a good point. I did not think of such corner cases. I will remove that mention then.

> Le 17 déc. 2019 à 06:33, SZEDER Gábor <szeder.dev@gmail.com> a écrit :
> 
> On Tue, Dec 17, 2019 at 05:07:42AM +0000, Philippe Blain via GitGitGadget wrote:
>> From: Philippe Blain <levraiphilippeblain@gmail.com>
>> 
>> 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
>> 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@gmail.com>
>> ---
>> Documentation/git-log.txt | 6 +++++-
>> Documentation/gitk.txt    | 6 +++++-
>> 2 files changed, 10 insertions(+), 2 deletions(-)
>> 
>> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
>> index b406bc4c48..1c52bf184d 100644
>> --- a/Documentation/git-log.txt
>> +++ b/Documentation/git-log.txt
>> @@ -77,7 +77,11 @@ produced by `--stat`, etc.
>> 	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.
>> -	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`.
> 
> ':<funcname>' doesn't imply '--function-context', but defines a line
> range starting at the function-name-looking line that first matches
> "funcname" and ending just before the next function-name-looking line,
> and line-log will then show that line range as context for each
> commit.  Although in many cases it shows diffs that look like as if
> '--function-context' were given, there are corner cases where they
> clearly differ, e.g. when following the history of a function that was
> at one point combined with the function directly below it.
> 
> Note the two commits in the middle that show two functions although
> only one of them was actually modified in each of those commits:
> 
>  $ git log --oneline -L:func:file.c
>  04b0c16 Combine funcA() and funcB() into func()
> 
>  diff --git a/file.c b/file.c
>  --- a/file.c
>  +++ b/file.c
>  @@ -1,9 +1,4 @@
>  -int funcA()
>  +int func()
>   {
>  -	return A;
>  -}
>  -
>  -int funcB()
>  -{
>  -	return B;
>  +	return A + B;
>   }
>  ed0d4d9 Modify funcB()
> 
>  diff --git a/file.c b/file.c
>  --- a/file.c
>  +++ b/file.c
>  @@ -1,9 +1,9 @@
>   int funcA()
>   {
>   	return A;
>   }
> 
>   int funcB()
>   {
>  -	return b;
>  +	return B;
>   }
>  0d4e9b5 Modify funcA()
> 
>  diff --git a/file.c b/file.c
>  --- a/file.c
>  +++ b/file.c
>  @@ -1,9 +1,9 @@
>   int funcA()
>   {
>  -	return a;
>  +	return A;
>   }
> 
>   int funcB()
>   {
>   	return b;
>   }
>  c3f8a44 Add funcA() and funcB()
> 
>  diff --git a/file.c b/file.c
>  --- /dev/null
>  +++ b/file.c
>  @@ -0,0 +1,9 @@
>  +int funcA()
>  +{
>  +	return a;
>  +}
>  +
>  +int funcB()
>  +{
>  +	return b;
>  +}
> 
> Now compare that to the same two middle commits shown with '-p
> --function-context', which doesn't show the unmodified function:
> 
>  $ git log --oneline -p --function-context file.c
>  04b0c16 Combine funcA() and funcB() into func()
>  diff --git a/file.c b/file.c
>  index 89571b3..33301ea 100644
>  --- a/file.c
>  +++ b/file.c
>  @@ -1,9 +1,4 @@
>  -int funcA()
>  +int func()
>   {
>  -	return A;
>  -}
>  -
>  -int funcB()
>  -{
>  -	return B;
>  +	return A + B;
>   }
>  ed0d4d9 Modify funcB()
>  diff --git a/file.c b/file.c
>  index 13592c8..89571b3 100644
>  --- a/file.c
>  +++ b/file.c
>  @@ -5,5 +5,5 @@ int funcA()
> 
>   int funcB()
>   {
>  -	return b;
>  +	return B;
>   }
>  0d4e9b5 Modify funcA()
>  diff --git a/file.c b/file.c
>  index 11e1e87..13592c8 100644
>  --- a/file.c
>  +++ b/file.c
>  @@ -1,6 +1,6 @@
>   int funcA()
>   {
>  -	return a;
>  +	return A;
>   }
> 
>   int funcB()
>  c3f8a44 Add funcA() and funcB()
>  diff --git a/file.c b/file.c
>  new file mode 100644
>  index 0000000..11e1e87
>  --- /dev/null
>  +++ b/file.c
>  @@ -0,0 +1,9 @@
>  +int funcA()
>  +{
>  +	return a;
>  +}
>  +
>  +int funcB()
>  +{
>  +	return b;
>  +}
Philippe Blain Dec. 18, 2019, 2:47 a.m. UTC | #4 
> Le 17 déc. 2019 à 10:33, Derrick Stolee <stolee@gmail.com> a écrit :
> 
> I would prefer the longer "--no-patch" over "-s", especially because you
> follow with several options in this style.

That’s a good idea. Thanks for the review!
diff mbox series

Patch

diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index b406bc4c48..1c52bf184d 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -77,7 +77,11 @@  produced by `--stat`, etc.
 	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.
-	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
+	(namely `--raw`, `--numstat`, `--shortstat`, `--dirstat`, `--summary`,
+	`--name-only`, `--name-status`, `--check`) are not currently implemented.
 +
 include::line-range-format.txt[]
 
diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
index 1eabb0aaf3..91993b9d4c 100644
--- a/Documentation/gitk.txt
+++ b/Documentation/gitk.txt
@@ -106,7 +106,11 @@  linkgit:git-rev-list[1] for a complete list.
 	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.
-	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
+	(namely `--raw`, `--numstat`, `--shortstat`, `--dirstat`, `--summary`,
+	`--name-only`, `--name-status`, `--check`) are not currently implemented.
 +
 *Note:* gitk (unlike linkgit:git-log[1]) currently only understands
 this option if you specify it "glued together" with its argument.  Do