[Feature request] Separate explicit fetch mapping from default fetch selection

[Feature request] Separate explicit fetch mapping from default fetch selection

[Douglas Puchalski (dpuchals)]

Git version: 2.55.0
Environment: macOS 26.6

I configure a remote to fetch only a small default set of branches:

    [remote "origin"]
        fetch = +refs/heads/main:refs/remotes/origin/main
        fetch = +refs/heads/team/*:refs/remotes/origin/team/*

This prevents `git fetch origin` from fetching and updating a very large
number of remote branches.

When I explicitly request another branch:

    git fetch origin topic/example

Git fetches the branch into FETCH_HEAD but does not create or update:

    refs/remotes/origin/topic/example

Consequently, the natural checkout command fails:

    git checkout -b topic/example origin/topic/example

The documented behavior couples two separate policies in
`remote.<name>.fetch`:

1. Which branches an ordinary `git fetch <remote>` selects automatically.
2. Where an explicitly requested branch is stored locally.

Please provide a configuration or default behavior under which an explicitly
named remote branch is stored as the corresponding remote-tracking ref, while
the remote's automatic fetch set remains restricted.

With that behavior, this sequence would work:

    git fetch origin topic/example
    git checkout -b topic/example origin/topic/example

It should not require fetching every remote branch, repeating the branch name
in a two-sided refspec, supplying `--refmap`, defining aliases, or handing the
result between commands through FETCH_HEAD. FETCH_HEAD is shared mutable state
and can be overwritten by another fetch between commands.

A backward-compatible opt-in configuration would address existing scripts
that rely on source-only fetches remaining temporary.

Relevant documentation:
https://git-scm <https://git-scm/>.com/docs/git-fetch

Re: [Feature request] Separate explicit fetch mapping from default fetch selection

[Junio C Hamano]

"Douglas Puchalski (dpuchals)" <dpuchals@cisco.com> writes:

> Git version: 2.55.0
> Environment: macOS 26.6
>
> I configure a remote to fetch only a small default set of branches:
>
>     [remote "origin"]
>         fetch = +refs/heads/main:refs/remotes/origin/main
>         fetch = +refs/heads/team/*:refs/remotes/origin/team/*
>
> This prevents `git fetch origin` from fetching and updating a very large
> number of remote branches.
>
> When I explicitly request another branch:
>
>     git fetch origin topic/example
>
> Git fetches the branch into FETCH_HEAD but does not create or update:
>
>     refs/remotes/origin/topic/example

I haven't thought things through, but I suspect that what you want
might be an opposite of explicitly listing what is tracked on
remote.*.fetch configuration, but having remotes/origin/* hierarchy
of refs as the source of the tracking information.

It was a long ago this was invented, and I haven't used it for
almost forever, but shouldn't this

    $ git fetch \
            --refmap="refs/heads/*:refs/remotes/origin/*" \
            origin topic/example

do what you want to do?  If so, perhaps it would make a good
starting point to make it easier to use (e.g., perhaps a
configuration variable can specify the refmap to be used, or
something).

Re: [Feature request] Separate explicit fetch mapping from default fetch selection

[Phillip Wood]

On 07/08/2026 03:42, Junio C Hamano wrote:
> "Douglas Puchalski (dpuchals)" <dpuchals@cisco.com> writes:
> 
>> Git version: 2.55.0
>> Environment: macOS 26.6
>>
>> I configure a remote to fetch only a small default set of branches:
>>
>>      [remote "origin"]
>>          fetch = +refs/heads/main:refs/remotes/origin/main
>>          fetch = +refs/heads/team/*:refs/remotes/origin/team/*
>>
>> This prevents `git fetch origin` from fetching and updating a very large
>> number of remote branches.
>>
>> When I explicitly request another branch:
>>
>>      git fetch origin topic/example
>>
>> Git fetches the branch into FETCH_HEAD but does not create or update:
>>
>>      refs/remotes/origin/topic/example

That annoys me too. There is a similar problem with the push refspec if 
you want to use it to map the refname rather than specify a default set 
of branches to push.

> I haven't thought things through, but I suspect that what you want
> might be an opposite of explicitly listing what is tracked on
> remote.*.fetch configuration, but having remotes/origin/* hierarchy
> of refs as the source of the tracking information.
> 
> It was a long ago this was invented, and I haven't used it for
> almost forever, but shouldn't this
> 
>      $ git fetch \
>              --refmap="refs/heads/*:refs/remotes/origin/*" \
>              origin topic/example
> 
> do what you want to do?  If so, perhaps it would make a good
> starting point to make it easier to use (e.g., perhaps a
> configuration variable can specify the refmap to be used, or
> something).

So we'd have something like "remote.<remote>.fetchMap" and 
"remote.<remote>.pushMap" that mapped refnames, but did not affect what 
gets fetched or push by default? That sounds useful (I've not thought 
through the interaction with the existing settings though).

One of my other bugbears about the refspec config is that the first 
matching one wins, rather than the longest match so you have to edit the 
config file rather than use "git config" to add a refspec that matches a 
sepcific branch, otherwise the default "refs/heads/*:..." that's created 
when the remote is added is used instead because it comes first.

Thanks

Phillip

Re: [Feature request] Separate explicit fetch mapping from default fetch selection

[Junio C Hamano]

Phillip Wood <phillip.wood123@gmail.com> writes:

>> It was a long ago this was invented, and I haven't used it for
>> almost forever, but shouldn't this
>> 
>>      $ git fetch \
>>              --refmap="refs/heads/*:refs/remotes/origin/*" \
>>              origin topic/example
>> 
>> do what you want to do?  If so, perhaps it would make a good
>> starting point to make it easier to use (e.g., perhaps a
>> configuration variable can specify the refmap to be used, or
>> something).
>
> So we'd have something like "remote.<remote>.fetchMap" and 
> "remote.<remote>.pushMap" that mapped refnames, but did not affect what 
> gets fetched or push by default? That sounds useful (I've not thought 
> through the interaction with the existing settings though).

As I said, I do not know what the final system should look like,
but the idea behind 'refmap' was to separate (A) the rule
describing the correspondence between reference names on their end
and those on our end, and (B) the specification of which source
references are transferred to the destination repository.  Since the
transfer can work both ways, we would need two sets of maps, one for
each direction.

Once established, I suspect that 'git fetch' could learn something
like the 'matching' mode that 'git push' has in 'push.default'.
Using that mode, the OP's everyday 'git fetch' would then: (1)
interact with the default remote; (2) decide which of their
references to fetch by reverse-mapping the remote-tracking branches
we already have using the fetch 'refmap'; and (3) update the
remote-tracking references using those references we decided to
fetch in the previous step.  If the OP decides to extend the area of
interest by fetching a new branch from the remote,

    $ git fetch origin a-new-topic

naming only the remote and their branch, we would know which
remote-tracking branch to store the result in and add a new
refs/remotes/origin/a-new-topic remote-tracking branch.  This would
automatically extend what the next 'git fetch' grabs from them.

Or something like that, perhaps?