remote.<name>.merge missing from the git-config man page?

remote.<name>.merge missing from the git-config man page?

[Fabien Terrani]

Hi all,

I was recently trying to understand the git-push command's behavior,
especially regarding the configuration values's resolution. I read the
following in the EXAMPLES section of the git-push man page:

> git push origin
>     Without additional configuration, pushes the current branch to the configured upstream (remote.origin.merge configuration variable) if it has the same name as the current branch, and errors out without pushing otherwise.

I then had a look at the git-config man page and I was surprised to
notice that there was no documentation at all about a
remote.<name>.merge or remote.origin.merge configuration value. I am
definitely not a git expert but this looks strange to me. Am I missing
something? Is remote.<name>.merge used by git at all?

(before mailing here, I tried carefully examining git's source code to
see if there was a remote.<name>.merge value used somewhere. I can't
be 100% positive since this was very complex to me, but I personally
couldn't find anything referencing remote.<name>.merge, while I found
code using other values like remote.<name>.push, push.default etc.)


Best regards

Re: remote.<name>.merge missing from the git-config man page?

[Eric Sunshine]

[cc:+adam +phillipe]

On Mon, Mar 8, 2021 at 7:11 AM Fabien Terrani <terranifabien@gmail.com> wrote:
> I was recently trying to understand the git-push command's behavior,
> especially regarding the configuration values's resolution. I read the
> following in the EXAMPLES section of the git-push man page:
>
> > git push origin
> >     Without additional configuration, pushes the current branch to the configured upstream (remote.origin.merge configuration variable) if it has the same name as the current branch, and errors out without pushing otherwise.
>
> I then had a look at the git-config man page and I was surprised to
> notice that there was no documentation at all about a
> remote.<name>.merge or remote.origin.merge configuration value. I am
> definitely not a git expert but this looks strange to me. Am I missing
> something? Is remote.<name>.merge used by git at all?

Yours is the second report[1] about this in a few weeks.

> (before mailing here, I tried carefully examining git's source code to
> see if there was a remote.<name>.merge value used somewhere. I can't
> be 100% positive since this was very complex to me, but I personally
> couldn't find anything referencing remote.<name>.merge, while I found
> code using other values like remote.<name>.push, push.default etc.)

I spent a bit of time going through the source code, as well, trying
to determine the correct name of this variable but didn't arrive at an
answer before having to turn to other tasks.

Hopefully, someone more familiar with this area of the project can
chime in with the correct answer and more useful response.

[1]: https://lore.kernel.org/git/CAAxrY9yjTKV8-K0AmO4fBmtDrSB4KkN_xKOMmtSb-dvixJNaEQ@mail.gmail.com/T/

Re: remote.<name>.merge missing from the git-config man page?

[Junio C Hamano]

Fabien Terrani <terranifabien@gmail.com> writes:

> I was recently trying to understand the git-push command's behavior,
> especially regarding the configuration values's resolution. I read the
> following in the EXAMPLES section of the git-push man page:
>
>> git push origin

>>     Without additional configuration, pushes the current branch
>>     to the configured upstream (remote.origin.merge configuration
>>     variable) if it has the same name as the current branch, and
>>     errors out without pushing otherwise.

Hmph, it seems it talks about the branch on the remote side that is
configured for the current branch to integrate with.  Most likely
that is misspelt "branch.<name>.merge" where <name> is the name of
the branch currently checked out.

The text comes from b2ed944a (push: switch default from "matching"
to "simple", 2013-01-04); I am a bit surprised how such a typo
survived this long ;-)

Re: remote.<name>.merge missing from the git-config man page?

[Taylor Blau]

On Mon, Mar 08, 2021 at 09:27:57AM -0800, Junio C Hamano wrote:
> >> git push origin
>
> >>     Without additional configuration, pushes the current branch
> >>     to the configured upstream (remote.origin.merge configuration
> >>     variable) if it has the same name as the current branch, and
> >>     errors out without pushing otherwise.
>
> Hmph, it seems it talks about the branch on the remote side that is
> configured for the current branch to integrate with.  Most likely
> that is misspelt "branch.<name>.merge" where <name> is the name of
> the branch currently checked out.

I agree; this should definitely refer to "branch.<name>.merge", not
"remote.<name>.merge" (which to my knowledge has never existed).

I had to double check that this "without additional configuration" is
right. Indeed:

  - The default value of the 'push.default' variable is "simple", which
    in a non-triangular workflow calls
    "builtin/push.c:setup_push_upstream()".

  - 'setup_push_upstream()' dies on L213 if strcmp(branch->refname,
    branch->merge[0]->src).

  - Othewrise, it sets up the expected refspec (to push the local branch
    to the remote branch 'branch.<name>.merge').

> The text comes from b2ed944a (push: switch default from "matching"
> to "simple", 2013-01-04); I am a bit surprised how such a typo
> survived this long ;-)

Me too :). Here's a patch to rectify the confusion:

--- >8 ---

Subject: [PATCH] Documentation/git-push.txt: correct configuration typo

In the EXAMPLES section, git-push(1) says that 'git push origin' pushes
the current branch to the value of the 'remote.origin.merge'
configuration.

This wording (which dates back to b2ed944af7 (push: switch default from
"matching" to "simple", 2013-01-04)) is incorrect. There is no such
configuration as 'remote.<name>.merge'. This likely was originally
intended to read "branch.<name>.merge" instead.

Indeed, when 'push.default' is 'simple' (which is the default value, and
is applicable in this scenario per "without additional configuration"),
setup_push_upstream() dies if the branch's local name does not match
'branch.<name>.merge'.

Correct this long-standing typo to resolve some recent confusion on the
intended behavior of this example.

Reported-by: Adam Sharafeddine <adam.shrfdn@gmail.com>
Reported-by: Fabien Terrani <terranifabien@gmail.com>
Signed-off-by: Taylor Blau <me@ttaylorr.com>
---
 Documentation/git-push.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index ab103c82cf..a953c7c387 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -600,7 +600,7 @@ EXAMPLES

 `git push origin`::
 	Without additional configuration, pushes the current branch to
-	the configured upstream (`remote.origin.merge` configuration
+	the configured upstream (`branch.<name>.merge` configuration
 	variable) if it has the same name as the current branch, and
 	errors out without pushing otherwise.
 +
--
2.30.0.667.g81c0cbc6fd

Re: remote.<name>.merge missing from the git-config man page?

[Andreas Schwab]

On Mär 08 2021, Taylor Blau wrote:

> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
> index ab103c82cf..a953c7c387 100644
> --- a/Documentation/git-push.txt
> +++ b/Documentation/git-push.txt
> @@ -600,7 +600,7 @@ EXAMPLES
>
>  `git push origin`::
>  	Without additional configuration, pushes the current branch to
> -	the configured upstream (`remote.origin.merge` configuration
> +	the configured upstream (`branch.<name>.merge` configuration
>  	variable) if it has the same name as the current branch, and
>  	errors out without pushing otherwise.

That doesn't say what <name> is.  Is that supposed to be <branch>?
Also, what is "it" referring to in "if it has the same name"?

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

Re: remote.<name>.merge missing from the git-config man page?

[Taylor Blau]

On Mon, Mar 08, 2021 at 09:14:33PM +0100, Andreas Schwab wrote:
> On Mär 08 2021, Taylor Blau wrote:
>
> > diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
> > index ab103c82cf..a953c7c387 100644
> > --- a/Documentation/git-push.txt
> > +++ b/Documentation/git-push.txt
> > @@ -600,7 +600,7 @@ EXAMPLES
> >
> >  `git push origin`::
> >  	Without additional configuration, pushes the current branch to
> > -	the configured upstream (`remote.origin.merge` configuration
> > +	the configured upstream (`branch.<name>.merge` configuration
> >  	variable) if it has the same name as the current branch, and
> >  	errors out without pushing otherwise.
>
> That doesn't say what <name> is.  Is that supposed to be <branch>?
> Also, what is "it" referring to in "if it has the same name"?

<name> refers to the currently-checked-out branch's local name. (That's
how it's used in Documentation/config/branch.txt).

The antecedent is "the current branch", so I think that this one may
already be quite clear if you read past the parenthesis.

Thanks,
Taylor

Re: remote.<name>.merge missing from the git-config man page?

[Andreas Schwab]

On Mär 08 2021, Taylor Blau wrote:

> On Mon, Mar 08, 2021 at 09:14:33PM +0100, Andreas Schwab wrote:
>> On Mär 08 2021, Taylor Blau wrote:
>>
>> > diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
>> > index ab103c82cf..a953c7c387 100644
>> > --- a/Documentation/git-push.txt
>> > +++ b/Documentation/git-push.txt
>> > @@ -600,7 +600,7 @@ EXAMPLES
>> >
>> >  `git push origin`::
>> >  	Without additional configuration, pushes the current branch to
>> > -	the configured upstream (`remote.origin.merge` configuration
>> > +	the configured upstream (`branch.<name>.merge` configuration
>> >  	variable) if it has the same name as the current branch, and
>> >  	errors out without pushing otherwise.
>>
>> That doesn't say what <name> is.  Is that supposed to be <branch>?
>> Also, what is "it" referring to in "if it has the same name"?
>
> <name> refers to the currently-checked-out branch's local name. (That's
> how it's used in Documentation/config/branch.txt).
>
> The antecedent is "the current branch", so I think that this one may
> already be quite clear if you read past the parenthesis.

That doesn't make sense: "if the current branch has the same name as the
current branch".

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

Re: remote.<name>.merge missing from the git-config man page?

[Taylor Blau]

On Mon, Mar 08, 2021 at 09:41:14PM +0100, Andreas Schwab wrote:
> >> >  `git push origin`::
> >> >  	Without additional configuration, pushes the current branch to
> >> > -	the configured upstream (`remote.origin.merge` configuration
> >> > +	the configured upstream (`branch.<name>.merge` configuration
> >> >  	variable) if it has the same name as the current branch, and
> >> >  	errors out without pushing otherwise.
> >>
> >> That doesn't say what <name> is.  Is that supposed to be <branch>?
> >> Also, what is "it" referring to in "if it has the same name"?
> >
> > <name> refers to the currently-checked-out branch's local name. (That's
> > how it's used in Documentation/config/branch.txt).
> >
> > The antecedent is "the current branch", so I think that this one may
> > already be quite clear if you read past the parenthesis.
>
> That doesn't make sense: "if the current branch has the same name as the
> current branch".

OK, now I see where your confusion is. I was incorrect in saying the
antecedent was "the current branch"; it should instead by "the
configured upstream". IOW, "if both your and the remote copy call the
branch you have checked out the same thing."

Re-reading the original wording, I still think that it is clear enough
to communicate what I wrote above, but if there is an alternative
wording you find clearer, I would certainly welcome suggestions.

Thanks,
Taylor

Re: remote.<name>.merge missing from the git-config man page?

[Andreas Schwab]

On Mär 08 2021, Taylor Blau wrote:

> On Mon, Mar 08, 2021 at 09:41:14PM +0100, Andreas Schwab wrote:
>> >> >  `git push origin`::
>> >> >  	Without additional configuration, pushes the current branch to
>> >> > -	the configured upstream (`remote.origin.merge` configuration
>> >> > +	the configured upstream (`branch.<name>.merge` configuration
>> >> >  	variable) if it has the same name as the current branch, and
>> >> >  	errors out without pushing otherwise.
>> >>
>> >> That doesn't say what <name> is.  Is that supposed to be <branch>?
>> >> Also, what is "it" referring to in "if it has the same name"?
>> >
>> > <name> refers to the currently-checked-out branch's local name. (That's
>> > how it's used in Documentation/config/branch.txt).
>> >
>> > The antecedent is "the current branch", so I think that this one may
>> > already be quite clear if you read past the parenthesis.
>>
>> That doesn't make sense: "if the current branch has the same name as the
>> current branch".
>
> OK, now I see where your confusion is. I was incorrect in saying the
> antecedent was "the current branch"; it should instead by "the
> configured upstream". IOW, "if both your and the remote copy call the
> branch you have checked out the same thing."

The configured upstream is the value of branch.<name>.merge, isn't it?
That would be the name of a remote, not the name of a branch.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

Re: remote.<name>.merge missing from the git-config man page?

[Taylor Blau]

On Mon, Mar 08, 2021 at 09:57:56PM +0100, Andreas Schwab wrote:
> The configured upstream is the value of branch.<name>.merge, isn't it?
> That would be the name of a remote, not the name of a branch.

Right; the '<name>' in 'branch.<name>.merge' is your local name for a
branch, but the value of that configuration is the remote's name.

> Andreas.

Thanks,
Taylor

Re: remote.<name>.merge missing from the git-config man page?

[Andreas Schwab]

On Mär 08 2021, Taylor Blau wrote:

> On Mon, Mar 08, 2021 at 09:57:56PM +0100, Andreas Schwab wrote:
>> The configured upstream is the value of branch.<name>.merge, isn't it?
>> That would be the name of a remote, not the name of a branch.
>
> Right; the '<name>' in 'branch.<name>.merge' is your local name for a
> branch, but the value of that configuration is the remote's name.

Sorry, I was misreading branch.<name>.merge as branch.<name>.remote.
Now it makes all sense to me.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

Re: remote.<name>.merge missing from the git-config man page?

[Junio C Hamano]

Andreas Schwab <schwab@linux-m68k.org> writes:

> On Mär 08 2021, Taylor Blau wrote:
>
>> On Mon, Mar 08, 2021 at 09:57:56PM +0100, Andreas Schwab wrote:
>>> The configured upstream is the value of branch.<name>.merge, isn't it?
>>> That would be the name of a remote, not the name of a branch.
>>
>> Right; the '<name>' in 'branch.<name>.merge' is your local name for a
>> branch, but the value of that configuration is the remote's name.
>
> Sorry, I was misreading branch.<name>.merge as branch.<name>.remote.
> Now it makes all sense to me.

OK, so do we have a version that is good to go?

Thanks.

-- >8 --
From: Taylor Blau <me@ttaylorr.com>
Date: Mon, 8 Mar 2021 13:43:47 -0500
Subject: [PATCH] Documentation/git-push.txt: correct configuration typo

In the EXAMPLES section, git-push(1) says that 'git push origin' pushes
the current branch to the value of the 'remote.origin.merge'
configuration.

This wording (which dates back to b2ed944af7 (push: switch default from
"matching" to "simple", 2013-01-04)) is incorrect. There is no such
configuration as 'remote.<name>.merge'. This likely was originally
intended to read "branch.<name>.merge" instead.

Indeed, when 'push.default' is 'simple' (which is the default value, and
is applicable in this scenario per "without additional configuration"),
setup_push_upstream() dies if the branch's local name does not match
'branch.<name>.merge'.

Correct this long-standing typo to resolve some recent confusion on the
intended behavior of this example.

Reported-by: Adam Sharafeddine <adam.shrfdn@gmail.com>
Reported-by: Fabien Terrani <terranifabien@gmail.com>
Signed-off-by: Taylor Blau <me@ttaylorr.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---

Notes (amlog):
    Message-Id: <YEZwY0721KvQNkK+@nand.local>

 Documentation/git-push.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index ab103c82cf..a953c7c387 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -600,7 +600,7 @@ EXAMPLES
 
 `git push origin`::
 	Without additional configuration, pushes the current branch to
-	the configured upstream (`remote.origin.merge` configuration
+	the configured upstream (`branch.<name>.merge` configuration
 	variable) if it has the same name as the current branch, and
 	errors out without pushing otherwise.
 +
-- 
2.31.0-rc2-171-g89112de4ba

Re: remote.<name>.merge missing from the git-config man page?

[Jonathan Nieder]

Junio C Hamano wrote:

> From: Taylor Blau <me@ttaylorr.com>
> Date: Mon, 8 Mar 2021 13:43:47 -0500
> Subject: [PATCH] Documentation/git-push.txt: correct configuration typo
>
> In the EXAMPLES section, git-push(1) says that 'git push origin' pushes
> the current branch to the value of the 'remote.origin.merge'
> configuration.
>
> This wording (which dates back to b2ed944af7 (push: switch default from
> "matching" to "simple", 2013-01-04)) is incorrect. There is no such
> configuration as 'remote.<name>.merge'. This likely was originally
> intended to read "branch.<name>.merge" instead.
>
> Indeed, when 'push.default' is 'simple' (which is the default value, and
> is applicable in this scenario per "without additional configuration"),
> setup_push_upstream() dies if the branch's local name does not match
> 'branch.<name>.merge'.
>
> Correct this long-standing typo to resolve some recent confusion on the
> intended behavior of this example.
>
> Reported-by: Adam Sharafeddine <adam.shrfdn@gmail.com>
> Reported-by: Fabien Terrani <terranifabien@gmail.com>
> Signed-off-by: Taylor Blau <me@ttaylorr.com>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/git-push.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Looks good.
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>

> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
> index ab103c82cf..a953c7c387 100644
> --- a/Documentation/git-push.txt
> +++ b/Documentation/git-push.txt
> @@ -600,7 +600,7 @@ EXAMPLES
>  
>  `git push origin`::
>  	Without additional configuration, pushes the current branch to
> -	the configured upstream (`remote.origin.merge` configuration
> +	the configured upstream (`branch.<name>.merge` configuration
>  	variable) if it has the same name as the current branch, and
>  	errors out without pushing otherwise.

From the discussion it seems this sentence has further room for
improvement, but that shouldn't block this straightforward typofix
patch.

A few ideas for further improvement:

- I think "the configured upstream" would read more clearly as "its
  configured upstream"

- the parenthesis could be a little clearer by adding a verb --- e.g.
  "as determined by the `branch.<name>.merge` configuration variable".
  Alternatively, is that implementation detail the right thing to
  mention?  Perhaps we could instead say something like "as configured
  using git branch --set-upstream-to" as a way to introduce the
  concept of a branch's upstream.

- the "it" in "it has the same name" is vague.  Does a branch's
  upstream represent the remote-tracking branch (e.g.,
  refs/remotes/origin/main) it merges or rebases against, or does it
  represent the remote branch (e.g., refs/heads/main in the remote
  repository pointed to by origin) it pulls from?

Putting those together, I could imagine something along the lines of

	Without additional configuration, this first checks that the
	current branch's configured upstream (see git-branch(1)
	--set-upstream-to) is a remote branch with the same name and
	then pushes there.  If there is no configured upstream or
	the configured upstream has a different name, it errors out
	without pushing.

Thanks,
Jonathan

Re: remote.<name>.merge missing from the git-config man page?

[Junio C Hamano]

Taylor Blau <me@ttaylorr.com> writes:

> On Mon, Mar 08, 2021 at 09:41:14PM +0100, Andreas Schwab wrote:
>> >> >  `git push origin`::
>> >> >  	Without additional configuration, pushes the current branch to
>> >> > -	the configured upstream (`remote.origin.merge` configuration
>> >> > +	the configured upstream (`branch.<name>.merge` configuration
>> >> >  	variable) if it has the same name as the current branch, and
>> >> >  	errors out without pushing otherwise.
>
> ... IOW, "if both your and the remote copy call the
> branch you have checked out the same thing."

Introducing a new term "remote copy" makes it even more confusing at
least to me.  And you are *not* checking out whatever branch any
remote repository has.  Your 'master' and my 'master' are different
entities.

I actually wonder what configuration the paragraph considers
fundamental and mandatory (as opposed to "additional" ones).

At the most basic "I just ran 'git clone' from somewhere" level,
remote.origin.url would be set and, branch.master.remote and
branch.master.merge are present.

I wonder if we should update the heading and extend the description
a bit further, e.g.

	`git push`::
		Without additional configuration, uses the
		`branch.<name>.remote` configuration variable for
		the branch that is currently checked-out to figure
		out which remote to push to, and pushes the current
		branch to update their branch with the same name.
		If `branch.<name>.merge` is set to a name different
		from `<name>`, however, errors out without pushing.

so that it makes it clear that .remote and .merge come in pair.