[PATCH 0/2] Documentation: fixups following followRemoteHEAD

[PATCH 0/2] Documentation: fixups following followRemoteHEAD

[Philippe Blain via GitGitGadget]

A small fixup and a wording improvement for the documentation of
remote.<name>.followRemoteHEAD.

Bence, thanks a lot for this new option, it is something I've been wanting
for a long time!

Philippe Blain (2):
  config/remote.txt: reunite 'severOption' description paragraphs
  config/remote.txt: improve wording for
    'remote.<name>.followRemoteHEAD'

 Documentation/config/remote.txt | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)


base-commit: e2067b49ecaef9b7f51a17ce251f9207f72ef52d
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1894%2Fphil-blain%2Ffollow-remote-head-doc-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1894/phil-blain/follow-remote-head-doc-v1
Pull-Request: https://github.com/git/git/pull/1894
-- 
gitgitgadget

[PATCH 1/2] config/remote.txt: reunite 'severOption' description paragraphs

[Philippe Blain via GitGitGadget]

From: Philippe Blain <levraiphilippeblain@gmail.com>

When 'remote.<name>.followRemoteHEAD' was added in b7f7d16562 (fetch:
add configuration for set_head behaviour, 2024-11-29), its description
was added to remote.txt in between the two paragraphs describing
'remote.<name>.serverOption'. Reunite these two paragraphs.

Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
 Documentation/config/remote.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/config/remote.txt b/Documentation/config/remote.txt
index 4118c219c13..1b9814e8aa4 100644
--- a/Documentation/config/remote.txt
+++ b/Documentation/config/remote.txt
@@ -101,6 +101,11 @@ remote.<name>.serverOption::
 	The default set of server options used when fetching from this remote.
 	These server options can be overridden by the `--server-option=` command
 	line arguments.
++
+This is a multi-valued variable, and an empty value can be used in a higher
+priority configuration file (e.g. `.git/config` in a repository) to clear
+the values inherited from a lower priority configuration files (e.g.
+`$HOME/.gitconfig`).
 
 remote.<name>.followRemoteHEAD::
 	How linkgit:git-fetch[1] should handle updates to `remotes/<name>/HEAD`.
@@ -114,8 +119,3 @@ remote.<name>.followRemoteHEAD::
 	Setting to "always" will silently update it to the value on the remote.
 	Finally, setting it to "never" will never change or create the local
 	reference.
-+
-This is a multi-valued variable, and an empty value can be used in a higher
-priority configuration file (e.g. `.git/config` in a repository) to clear
-the values inherited from a lower priority configuration files (e.g.
-`$HOME/.gitconfig`).
-- 
gitgitgadget

[PATCH 2/2] config/remote.txt: improve wording for 'remote.<name>.followRemoteHEAD'

[Philippe Blain via GitGitGadget]

From: Philippe Blain <levraiphilippeblain@gmail.com>

Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
 Documentation/config/remote.txt | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/config/remote.txt b/Documentation/config/remote.txt
index 1b9814e8aa4..25fe219d103 100644
--- a/Documentation/config/remote.txt
+++ b/Documentation/config/remote.txt
@@ -110,12 +110,12 @@ the values inherited from a lower priority configuration files (e.g.
 remote.<name>.followRemoteHEAD::
 	How linkgit:git-fetch[1] should handle updates to `remotes/<name>/HEAD`.
 	The default value is "create", which will create `remotes/<name>/HEAD`
-	if it exists on the remote, but not locally, but will not touch an
-	already existing local reference. Setting to "warn" will print
-	a message if the remote has a different value, than the local one and
+	if it exists on the remote, but not locally; this will not touch an
+	already existing local reference. Setting it to "warn" will print
+	a message if the remote has a different value than the local one;
 	in case there is no local reference, it behaves like "create".
 	A variant on "warn" is "warn-if-not-$branch", which behaves like
 	"warn", but if `HEAD` on the remote is `$branch` it will be silent.
-	Setting to "always" will silently update it to the value on the remote.
-	Finally, setting it to "never" will never change or create the local
-	reference.
+	Setting it to "always" will silently update `remotes/<name>/HEAD` to
+	the value on the remote.  Finally, setting it to "never" will never
+	change or create the local reference.
-- 
gitgitgadget

Re: [PATCH 1/2] config/remote.txt: reunite 'severOption' description paragraphs

[Bence Ferdinandy]

On Fri Feb 14, 2025 at 18:36, Philippe Blain via GitGitGadget <gitgitgadget@gmail.com> wrote:
> From: Philippe Blain <levraiphilippeblain@gmail.com>
>
> When 'remote.<name>.followRemoteHEAD' was added in b7f7d16562 (fetch:
> add configuration for set_head behaviour, 2024-11-29), its description
> was added to remote.txt in between the two paragraphs describing
> 'remote.<name>.serverOption'. Reunite these two paragraphs.
>
> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
> ---

Auch, that was sloppy. Thanks for cleaning up the mistake!

Re: [PATCH 2/2] config/remote.txt: improve wording for 'remote.<name>.followRemoteHEAD'

[Bence Ferdinandy]

On Fri Feb 14, 2025 at 18:36, Philippe Blain via GitGitGadget <gitgitgadget@gmail.com> wrote:
> From: Philippe Blain <levraiphilippeblain@gmail.com>
>
> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
> ---
>  Documentation/config/remote.txt | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/config/remote.txt b/Documentation/config/remote.txt
> index 1b9814e8aa4..25fe219d103 100644
> --- a/Documentation/config/remote.txt
> +++ b/Documentation/config/remote.txt
> @@ -110,12 +110,12 @@ the values inherited from a lower priority configuration files (e.g.
>  remote.<name>.followRemoteHEAD::
>  	How linkgit:git-fetch[1] should handle updates to `remotes/<name>/HEAD`.
>  	The default value is "create", which will create `remotes/<name>/HEAD`
> -	if it exists on the remote, but not locally, but will not touch an
> -	already existing local reference. Setting to "warn" will print
> -	a message if the remote has a different value, than the local one and
> +	if it exists on the remote, but not locally; this will not touch an
> +	already existing local reference. Setting it to "warn" will print
> +	a message if the remote has a different value than the local one;
>  	in case there is no local reference, it behaves like "create".
>  	A variant on "warn" is "warn-if-not-$branch", which behaves like
>  	"warn", but if `HEAD` on the remote is `$branch` it will be silent.
> -	Setting to "always" will silently update it to the value on the remote.
> -	Finally, setting it to "never" will never change or create the local
> -	reference.
> +	Setting it to "always" will silently update `remotes/<name>/HEAD` to
> +	the value on the remote.  Finally, setting it to "never" will never
> +	change or create the local reference.

I'm personally not a huge fan of semicolons, but I do agree that the text does
not flow particularly well. Wouldn't it actually make sense to format this as
a list, with an entry for each option? The would probably also help in quickly
parsing how many options there are.

Re: [PATCH 1/2] config/remote.txt: reunite 'severOption' description paragraphs

[Junio C Hamano]

"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Philippe Blain <levraiphilippeblain@gmail.com>
>
> When 'remote.<name>.followRemoteHEAD' was added in b7f7d16562 (fetch:
> add configuration for set_head behaviour, 2024-11-29), its description
> was added to remote.txt in between the two paragraphs describing
> 'remote.<name>.serverOption'. Reunite these two paragraphs.

Ouch.  Thanks for spotting and fixing.

>
> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
> ---
>  Documentation/config/remote.txt | 10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/config/remote.txt b/Documentation/config/remote.txt
> index 4118c219c13..1b9814e8aa4 100644
> --- a/Documentation/config/remote.txt
> +++ b/Documentation/config/remote.txt
> @@ -101,6 +101,11 @@ remote.<name>.serverOption::
>  	The default set of server options used when fetching from this remote.
>  	These server options can be overridden by the `--server-option=` command
>  	line arguments.
> ++
> +This is a multi-valued variable, and an empty value can be used in a higher
> +priority configuration file (e.g. `.git/config` in a repository) to clear
> +the values inherited from a lower priority configuration files (e.g.
> +`$HOME/.gitconfig`).
>  
>  remote.<name>.followRemoteHEAD::
>  	How linkgit:git-fetch[1] should handle updates to `remotes/<name>/HEAD`.
> @@ -114,8 +119,3 @@ remote.<name>.followRemoteHEAD::
>  	Setting to "always" will silently update it to the value on the remote.
>  	Finally, setting it to "never" will never change or create the local
>  	reference.
> -+
> -This is a multi-valued variable, and an empty value can be used in a higher
> -priority configuration file (e.g. `.git/config` in a repository) to clear
> -the values inherited from a lower priority configuration files (e.g.
> -`$HOME/.gitconfig`).

Re: [PATCH 2/2] config/remote.txt: improve wording for 'remote.<name>.followRemoteHEAD'

[Philippe Blain]

Hi Bence,

Le 2025-02-14 à 17:05, Bence Ferdinandy a écrit :
> 
> On Fri Feb 14, 2025 at 18:36, Philippe Blain via GitGitGadget <gitgitgadget@gmail.com> wrote:
>> From: Philippe Blain <levraiphilippeblain@gmail.com>
>>
>> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
>> ---
>>  Documentation/config/remote.txt | 12 ++++++------
>>  1 file changed, 6 insertions(+), 6 deletions(-)
>>
>> diff --git a/Documentation/config/remote.txt b/Documentation/config/remote.txt
>> index 1b9814e8aa4..25fe219d103 100644
>> --- a/Documentation/config/remote.txt
>> +++ b/Documentation/config/remote.txt
>> @@ -110,12 +110,12 @@ the values inherited from a lower priority configuration files (e.g.
>>  remote.<name>.followRemoteHEAD::
>>  	How linkgit:git-fetch[1] should handle updates to `remotes/<name>/HEAD`.
>>  	The default value is "create", which will create `remotes/<name>/HEAD`
>> -	if it exists on the remote, but not locally, but will not touch an
>> -	already existing local reference. Setting to "warn" will print
>> -	a message if the remote has a different value, than the local one and
>> +	if it exists on the remote, but not locally; this will not touch an
>> +	already existing local reference. Setting it to "warn" will print
>> +	a message if the remote has a different value than the local one;
>>  	in case there is no local reference, it behaves like "create".
>>  	A variant on "warn" is "warn-if-not-$branch", which behaves like
>>  	"warn", but if `HEAD` on the remote is `$branch` it will be silent.
>> -	Setting to "always" will silently update it to the value on the remote.
>> -	Finally, setting it to "never" will never change or create the local
>> -	reference.
>> +	Setting it to "always" will silently update `remotes/<name>/HEAD` to
>> +	the value on the remote.  Finally, setting it to "never" will never
>> +	change or create the local reference.
> 
> I'm personally not a huge fan of semicolons, but I do agree that the text does
> not flow particularly well. Wouldn't it actually make sense to format this as
> a list, with an entry for each option? The would probably also help in quickly
> parsing how many options there are.

I think lists are a good idea in general, but since there is no uniformity with regards
to that in the rest of the documentation, I would keep it as-is for this series.

Thanks,

Philippe.