Skip to content

Improve line log documentation #494

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
phil-blain wants to merge 2 commits into from
Closed

Improve line log documentation #494

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e68ef0c
doc: log, gitk: document accepted line-log diff formats
phil-blain Dec 14, 2019
c7d4897
doc: log, gitk: line-log arguments must exist in starting revision
phil-blain Dec 16, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions Documentation/git-log.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,8 +76,12 @@ produced by `--stat`, etc.
(or the function name regex <funcname>) within the <file>. You may
Copy link

@gitgitgadget gitgitgadget bot Dec 17, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Derrick Stolee wrote (reply to this):

On 12/17/2019 12:07 AM, Philippe Blain via GitGitGadget wrote:
> From: Philippe Blain <levraiphilippeblain@gmail.com>
> 
> 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
> revision, or else the command exits with a fatal error.
> 
> This is not obvious in the documentation, so add a note to that
> effect.

This seems helpful. Thanks.

-Stolee

Copy link

@gitgitgadget gitgitgadget bot Dec 17, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

Derrick Stolee <stolee@gmail.com> writes:

> On 12/17/2019 12:07 AM, Philippe Blain via GitGitGadget wrote:
>> From: Philippe Blain <levraiphilippeblain@gmail.com>
>> 
>> 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
>> revision, or else the command exits with a fatal error.
>> 
>> This is not obvious in the documentation, so add a note to that
>> effect.
>
> This seems helpful. Thanks.

Even when you specify <start> or <end> as a line number, they must
exist in the starting revision or it would be a fatal error.  If we
are clarifying with this patch for completeness, I think we should
also mention it together.  

Or we could even drop the mention of regex and say <start> and
<end>, regardless of how they are specified (including :<funcname>
format), must exist in the starting revision.

Copy link

@gitgitgadget gitgitgadget bot Dec 18, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Philippe Blain wrote (reply to this):


> Le 17 déc. 2019 à 13:16, Junio C Hamano <gitster@pobox.com> a écrit :
> Even when you specify <start> or <end> as a line number, they must
> exist in the starting revision or it would be a fatal error.  If we
> are clarifying with this patch for completeness, I think we should
> also mention it together.  
Thanks for the feedback. I did some tests : 
    git log -L 73,2000000085:Documentation/git-log.txt
does not error and shows the history from line 73 to the end of the file.
    git log -L 300,2000000085:Documentation/git-log.txt 
errors out:
    fatal: file Documentation/git-log.txt has only 239 lines
But 
    git log -L 300,-2000000085:Documentation/git-log.txt
does not error out and shows the history for the whole file. Also,
    git log -L 1,-2000000085:Documentation/git-log.txt
does not error out and gives the history for the first line.

So I think that it�s really only regex that must match...

Copy link

@gitgitgadget gitgitgadget bot Dec 18, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Derrick Stolee wrote (reply to this):

On 12/17/2019 10:28 PM, Philippe Blain wrote:
> 
>> Le 17 déc. 2019 à 13:16, Junio C Hamano <gitster@pobox.com> a écrit :
>> Even when you specify <start> or <end> as a line number, they must
>> exist in the starting revision or it would be a fatal error.  If we
>> are clarifying with this patch for completeness, I think we should
>> also mention it together.  
...
>     git log -L 300,2000000085:Documentation/git-log.txt 
> errors out:
>     fatal: file Documentation/git-log.txt has only 239 lines

This case seems important enough to include what it means to "match".

Specifically, the range must match at least one line in the file.

> But 
>     git log -L 300,-2000000085:Documentation/git-log.txt
> does not error out and shows the history for the whole file. Also,
>     git log -L 1,-2000000085:Documentation/git-log.txt
> does not error out and gives the history for the first line.

Negative numbers in the ranges are a bit strange to include, and the
large magnitude you include here seems unnecessary for the test.
However, it appears that we do store signed values in the line-log
machinery:

/* A range [start,end].  Lines are numbered starting at 0, and the
 * ranges include start but exclude end. */
struct range {
	long start, end;
};

Perhaps these should be replaced with an unsigned value instead,
just to be clear that negative values do not make sense in this
context?

Or rather, do we want to enforce start < end if they are to be
valuable? We apparently do assert() this in
range_set_check_invariants() for all that does.

The current behavior of showing only the first line
is a strange byproduct of allowing these odd ranges, but we may
want to keep it for consistency. That would imply we allow
start <= end, and auto-correct these negative values to have
end = start. (This does not fix the 300,-1 case, but that
is strange enough to be considered a bug, right?)

Thanks,
-Stolee

Copy link

@gitgitgadget gitgitgadget bot Dec 18, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, SZEDER Gábor wrote (reply to this):

On Tue, Dec 17, 2019 at 10:28:37PM -0500, Philippe Blain wrote:
> 
> > Le 17 déc. 2019 à 13:16, Junio C Hamano <gitster@pobox.com> a écrit :
> > Even when you specify <start> or <end> as a line number, they must
> > exist in the starting revision or it would be a fatal error.  If we
> > are clarifying with this patch for completeness, I think we should
> > also mention it together.  
> Thanks for the feedback. I did some tests : 

I'll swap the order of your first two tests:

>     git log -L 300,2000000085:Documentation/git-log.txt 
> errors out:
>     fatal: file Documentation/git-log.txt has only 239 lines

Here the entire line range is outside of the file, so there is not
much we can do about it, but error out.

An alternative would be to treat it as an empty line range and then
don't show any commits but exit silently, but I think that would be
confusing ("why didn't I get any output?!"), and telling the user
what's wrong is better ("Ah, ok, I mistyped 192 as 912").

>     git log -L 73,2000000085:Documentation/git-log.txt
> does not error and shows the history from line 73 to the end of the file.

Here there is an overlap between the given line range and the file
(lines 73-239), so we have two possibilities:

  - be strict and error out saying that the <end> doesn't make sense.

  - be lax about it, and interpret the <end> as the end of file.  This
    allows for cases like "I want line log from here to the end of
    file, but instead of finding out the exact number of lines in the
    file I'll just say 999999 that is surely larger than the file, and
    you shall do what I mean".

Those who implemented the line-log feature chose the latter.  I think
it's the better choice.

> But 
>     git log -L 300,-2000000085:Documentation/git-log.txt
> does not error out and shows the history for the whole file. Also,
>     git log -L 1,-2000000085:Documentation/git-log.txt
> does not error out and gives the history for the first line.

These are a variant of the previous case, with the difference that
because of the '-' in <end> it is not an absolute line number but
relative, and is interpreted as that many lines before <start> (i.e.
in this case <start> actually means the end of the line range).

I think the same argument can be made about <end> pointing past the
beginning of the file, though, arguably, it's not as useful, because
the first line as always 1, and '-L 123,-99999' is more keystrokes
than '-L 1,123'.

> So I think that it’s really only regex that must match...

Copy link

@gitgitgadget gitgitgadget bot Dec 18, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, SZEDER Gábor wrote (reply to this):

On Wed, Dec 18, 2019 at 05:55:25AM -0500, Derrick Stolee wrote:
> On 12/17/2019 10:28 PM, Philippe Blain wrote:
> > 
> >> Le 17 déc. 2019 à 13:16, Junio C Hamano <gitster@pobox.com> a écrit :
> >> Even when you specify <start> or <end> as a line number, they must
> >> exist in the starting revision or it would be a fatal error.  If we
> >> are clarifying with this patch for completeness, I think we should
> >> also mention it together.  
> ...
> >     git log -L 300,2000000085:Documentation/git-log.txt 
> > errors out:
> >     fatal: file Documentation/git-log.txt has only 239 lines
> 
> This case seems important enough to include what it means to "match".
> 
> Specifically, the range must match at least one line in the file.
> 
> > But 
> >     git log -L 300,-2000000085:Documentation/git-log.txt
> > does not error out and shows the history for the whole file. Also,
> >     git log -L 1,-2000000085:Documentation/git-log.txt
> > does not error out and gives the history for the first line.
> 
> Negative numbers in the ranges are a bit strange to include, and the
> large magnitude you include here seems unnecessary for the test.
> However, it appears that we do store signed values in the line-log
> machinery:
> 
> /* A range [start,end].  Lines are numbered starting at 0, and the
>  * ranges include start but exclude end. */
> struct range {
> 	long start, end;
> };
> 
> Perhaps these should be replaced with an unsigned value instead,
> just to be clear that negative values do not make sense in this
> context?
> 
> Or rather, do we want to enforce start < end if they are to be
> valuable? We apparently do assert() this in
> range_set_check_invariants() for all that does.

We have different contexts for start,end here: the '-L <start>,<end>'
specified on the command line and the 'start' and 'end' fields of the
internal 'struct range' are not the same and different constraints
apply to them.

'-L X,+Y' and '-L X,-Y' are explicitly allowed, and mean that Y is
interpreted relative to X, the former meaning Y lines starting at X,
while the latter meaning Y lines ending at X.  These are interpreted
while parsing the '-L ...' options, during which we do pass around
negative values in (signed) long parameters, see
line-range.c:parse_loc().  (though, arguably, having unsigned types
and a separate flag parameter might make the code more clear)

The purpose of range_set_check_invariants() is different: as the
file's content changes over its history the internal line ranges must
be adjusted (grown, shrunk, shifted around or sometimes even merged)
accordingly, and this function makes sure that the resulting 'struct
range' instances after these adjustments still make sense, because the
rest of the line log machinery expects sorted and non-overlapping line
ranges.


> The current behavior of showing only the first line
> is a strange byproduct of allowing these odd ranges, but we may
> want to keep it for consistency. That would imply we allow
> start <= end, and auto-correct these negative values to have
> end = start. (This does not fix the 300,-1 case, but that
> is strange enough to be considered a bug, right?)
> 
> Thanks,
> -Stolee
>

Copy link

@gitgitgadget gitgitgadget bot Dec 18, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

Derrick Stolee <stolee@gmail.com> writes:

> On 12/17/2019 10:28 PM, Philippe Blain wrote:
>> 
>>> Le 17 déc. 2019 à 13:16, Junio C Hamano <gitster@pobox.com> a écrit :
>>> Even when you specify <start> or <end> as a line number, they must
>>> exist in the starting revision or it would be a fatal error.  If we
>>> are clarifying with this patch for completeness, I think we should
>>> also mention it together.  
> ...
>>     git log -L 300,2000000085:Documentation/git-log.txt 
>> errors out:
>>     fatal: file Documentation/git-log.txt has only 239 lines
>
> This case seems important enough to include what it means to "match".

Yup, that is why I suggested not to focus too much on regexp and
"match"-ing, but express it in terms of the lines that are specified
by given arguments to "exist".  The word "match" gives an incorrect
connotation that the description in the paragraph that uses the verb
applies only to regexp.

Copy link

@gitgitgadget gitgitgadget bot Dec 26, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Philippe Blain wrote (reply to this):


> Le 18 déc. 2019 à 12:59, Junio C Hamano <gitster@pobox.com> a écrit :
> ...
> Yup, that is why I suggested not to focus too much on regexp and
> "match"-ing, but express it in terms of the lines that are specified
> by given arguments to "exist".  The word "match" gives an incorrect
> connotation that the description in the paragraph that uses the verb
> applies only to regexp.

I agree. Thanks for the suggestion. I changed it to « exist » in v2.

not give any pathspec limiters. This is currently limited to
Copy link

@gitgitgadget gitgitgadget bot Dec 17, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, SZEDER Gábor wrote (reply to this):

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;
  +}

Copy link

@gitgitgadget gitgitgadget bot Dec 18, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Philippe Blain wrote (reply to this):

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;
>  +}

Copy link

@gitgitgadget gitgitgadget bot Dec 17, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Derrick Stolee wrote (reply to this):

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

Copy link

@gitgitgadget gitgitgadget bot Dec 18, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Philippe Blain wrote (reply to this):


> 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!

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.
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`,
`--name-only`, `--name-status`, `--check`) are not currently implemented.
+
include::line-range-format.txt[]

Expand Down
8 changes: 6 additions & 2 deletions Documentation/gitk.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,8 +105,12 @@ linkgit:git-rev-list[1] for a complete list.
(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.
You can specify this option more than once.
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`,
`--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
Expand Down