Re: `git fetch --refmap=<refspec>… <repository> <refspec>… ` providing NON-empty <refspec> to the --refmap ALSO causes Git to ignore the configured refspecs

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 4, 2024, 16:47 UTC
Message-ID: <xmqq5xrbbc36.fsf@gitster.g>
In-Reply-To: <562614e4-5384-4220-896a-20b3f79771bd@kdbg.org>

Johannes Sixt <j6t@kdbg.org> writes:

Show 11 quoted lines

> Am 04.09.24 um 13:12 schrieb Han Jiang:
>> 1. If the doc says "providing an empty <refspec> to the --refmap
>> option causes Git to ignore the configured refspecs and rely entirely
>> on the refspecs supplied as command-line arguments" then it's
>> reasonable to guess that "providing a non-empty <refspec> will not do
>> those".
>
> Fair enough. But then in section "Configured Remote-tracking Branches"
> it is said that "The latter use of the remote.<repository>.fetch values
> can be overridden by giving the --refmap=<refspec> parameter(s) on the
> command line." So... I dunno. Just my 2c.

This cuts both ways, I suspect.  It is so unusual to say

    git fetch --refmap="" foo bar baz

to use an empty string as <refspec> in "--refmap=<refspec>", simply because you would not say

    git fetch origin ""

and expect the empty string is a <refspec> in "git fetch origin <refspec>".

Any string other than an empty string, e.g.

    git fetch --refmap="refs/heads/*:refs/prefetch/x/*" foo bar baz

would have an extra side effect of storing what gets fetched, when your primary focus is "I want the command to ignore the configured refspec".

For these reasons, I would actually say it is quite fair for the documentation to single out the empty string case as an idiom that may be hard for readers to figure out for themselves without being told.

I would not be opposed to add a sentence or two to clarify what happens when a non-empty <refspec> is used, though.

Thanks.