doc: add documentation for git log --no-follow
diff mbox series

Message ID 85e71c97-9e0a-863e-179f-a6e1f14365ce@voucoux.fr
State New
Headers show
Series
  • doc: add documentation for git log --no-follow
Related show

Commit Message

Étienne Servais Jan. 31, 2020, 11:24 p.m. UTC
This feature was added by commit
076c98372e (log: add "log.follow" configuration variable, 2015-07-07)
but remained undocumented.

Signed-off-by: Étienne Servais <etienne.servais@voucoux.fr>
---
This is my first patch to git \o/
Sent with thunderbird with help of format-patch'doc (So, it works!).
I've tested the patch and git am works well on maint and next.
I couldn't figure if I shall merge the --no-follow doc with the follow
as is done for --no-decorate and --decorate just after. 
I couldn't think of a proper phrasing so I'll be glad to get suggestion on this.

 Documentation/git-log.txt | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

Comments

Jeff King Feb. 1, 2020, 11:16 a.m. UTC | #1
On Sat, Feb 01, 2020 at 12:24:31AM +0100, Étienne Servais wrote:

> This feature was added by commit
> 076c98372e (log: add "log.follow" configuration variable, 2015-07-07)
> but remained undocumented.

That commit just touched the code; it was originally added by aebbcf5797
(diff: accept --no-follow option, 2012-09-21). But I think the general
intent of your patch is still valid.

> Signed-off-by: Étienne Servais <etienne.servais@voucoux.fr>
> ---
> This is my first patch to git \o/
> Sent with thunderbird with help of format-patch'doc (So, it works!).

Yeah, everything looks good there (no whitespace damage, etc).

> I couldn't figure if I shall merge the --no-follow doc with the follow
> as is done for --no-decorate and --decorate just after.

I think it would make more sense to just put it with --follow, like:

  [--no-]follow::

which matches how --use-mailmap is defined, for instance.

> @@ -205,7 +208,8 @@ log.follow::
>  	If `true`, `git log` will act as if the `--follow` option was used when
>  	a single <path> is given.  This has the same limitations as `--follow`,
>  	i.e. it cannot be used to follow multiple files and does not work well
> -	on non-linear history.
> +	on non-linear history. This setting can be disabled by the `--no-follow`
> +	option.

I'm on the fence on this hunk. There are a number of config options that
can be canceled or overridden by command-line options. It's a normal
pattern for the "--no" variant to do so. So while it often doesn't hurt
to give a pointer in the right direction, I don't know that we'd want to
start doing so in every such case.

-Peff
Étienne Servais Feb. 3, 2020, 8:27 p.m. UTC | #2
Le 01/02/2020 à 12:16, Jeff King a écrit :
> On Sat, Feb 01, 2020 at 12:24:31AM +0100, Étienne Servais wrote:
> 
>> This feature was added by commit
>> 076c98372e (log: add "log.follow" configuration variable, 2015-07-07)
>> but remained undocumented.
> 
> That commit just touched the code; it was originally added by aebbcf5797
> (diff: accept --no-follow option, 2012-09-21). But I think the general
> intent of your patch is still valid.

Good catch. Corrected in upcoming patch v2

>> I couldn't figure if I shall merge the --no-follow doc with the follow
>> as is done for --no-decorate and --decorate just after.
> 
> I think it would make more sense to just put it with --follow, like:
> 
>   [--no-]follow::
> 
> which matches how --use-mailmap is defined, for instance.

Ok, I've turned it to (inspired by the --[no-]rename-empty doc)

---follow::
-       Continue listing the history of a file beyond renames
+--[no-]follow::
+       Whether to continue listing the history of a file beyond renames
        (works only for a single file).


> 
>> @@ -205,7 +208,8 @@ log.follow::
>>  	If `true`, `git log` will act as if the `--follow` option was used when
>>  	a single <path> is given.  This has the same limitations as `--follow`,
>>  	i.e. it cannot be used to follow multiple files and does not work well
>> -	on non-linear history.
>> +	on non-linear history. This setting can be disabled by the `--no-follow`
>> +	option.
> 
> I'm on the fence on this hunk. There are a number of config options that
> can be canceled or overridden by command-line options. It's a normal
> pattern for the "--no" variant to do so. So while it often doesn't hurt
> to give a pointer in the right direction, I don't know that we'd want to
> start doing so in every such case.

OK. I had just borrowed that sentence from notes.displayRef few lines below.
Some config options doc follow this direction like log.abbrevCommit or log.mailmap.

I'll follow you on this.

Patch
diff mbox series

diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index bed09bb09e..cc2ad98167 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -28,6 +28,9 @@  OPTIONS
 	Continue listing the history of a file beyond renames
 	(works only for a single file).
 
+--no-follow::
+	Override the log.follow configuration.
+
 --no-decorate::
 --decorate[=short|full|auto|no]::
 	Print out the ref names of any commits that are shown. If 'short' is
@@ -205,7 +208,8 @@  log.follow::
 	If `true`, `git log` will act as if the `--follow` option was used when
 	a single <path> is given.  This has the same limitations as `--follow`,
 	i.e. it cannot be used to follow multiple files and does not work well
-	on non-linear history.
+	on non-linear history. This setting can be disabled by the `--no-follow`
+	option.
 
 log.showRoot::
 	If `false`, `git log` and related commands will not treat the