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

[Junio C Hamano <gitster@pobox.com>]

Johannes Sixt <j6t@kdbg.org> writes:

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