Re: [PATCH] checkout: add remoteBranchTemplate config for DWIM branch names

[pasteley <ceasebeing@gmail.com>]

You're right that same-named branches are the ideal Git workflow, and I
agree this patch should not encourage drifting away from that model.

The motivation here is for cases where the name mismatch is imposed by
external constraints, not chosen by developers. For example:

1. Server-side policies/hooks that require a namespace on the remote
    (e.g. `team/*`, `users/<id>/*`, `release/*`).
2. Hosting / mirroring setups where remote branches live under a fixed
    prefix for organizational or access-control reasons.
3. Migrations where the remote branch layout is constrained by the
    target system, while local developer workflows assume short names.

In these scenarios developers do not create the problem, they inherit it.
The alternative today is to type the prefixed remote name everywhere and
give up DWIM convenience (e.g. `git checkout foo` no longer does the
"natural" thing).

This remains opt-in via `checkout.remoteBranchTemplate`, so only workflows
that explicitly configure it change behavior; defaults stay unchanged.
Explicit operations still bypass the template (e.g. `-b/-c <name>` and an
explicit push refspec keep full user control).

Git already supports name mismatches in a few places:
* `remote.<name>.fetch` allows arbitrary mappings for remote refs.
* `branch.<name>.merge` can track a differently named remote branch.
* `push.default=upstream` pushes to the configured upstream even if names
   differ.

However, configuring `remote.<name>.push` does not solve the DWIM checkout
problem: users still need to know the full remote branch name to check it
out, and wildcard push refspecs can have surprising scope (they can match
many branches unless the user is always explicit). This patch keeps the
scope narrow: it only affects cases where Git is already "guessing" the
remote side (checkout/switch/worktree --guess-remote, and automatic
upstream setup).

> Once "git checkout foo" is taught to do the same as "git checkout -b
> extra-foo -t origin/foo", it would create:
>
> [branch "extra-foo"]
> remote = origin
> merge = refs/heads/foo

Yes, but only for the DWIM path where Git derives the remote branch. When
the user explicitly names the local branch, we do not apply the template.

> But then what should happen when the user is using "matching push"?

While `push.default=matching` has been deprecated since Git 2.0 (~ 2014),
we still can handle this corner case by detecting the incompatibility
and providing a clear error message.

Thanks for the thorough review,
pasteley

On 22/12/2025 5:40 AM, Junio C Hamano wrote:
> "Pasteley Absurda via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: pasteley <ceasebeing@gmail.com>
>>
>> Add checkout.remoteBranchTemplate to apply a template pattern when
>> searching for remote branches during checkout DWIM and when creating
>> remote branches with push.autoSetupRemote.
>>
>> Template uses printf-style placeholders (%s for branch name). For
>> example, with "feature/%s", checking out "foo"
>> searches for "origin/feature/foo" and creates local "foo"
>> tracking it. Pushing with autoSetupRemote creates "origin/feature/bar"
>> from local "bar".
>>
>> Useful when remote branches use prefixes but local branches don't.
> It fells that this is presented backwards.  The usefulness of the
> layout that names local branches deliberately differently from their
> remote counterparts needs to be justified first.  Only after that,
> we can consider adding extra mechanism to support such a layout.
>
>
> Once "git checkout foo" is taught to do the same as "git checkout -b
> extra-foo -t origin/foo", it would create
>
> 	[branch "extra-foo"]
> 		remote = origin
> 		merge = refs/heads/foo
>
> but the push side would need extra work, and that is why you needed
> to muck with the push refspec.  But then what should happen when the
> user is using "we do not bother remembering what branches to push
> there; the remote repository remembers that for us", aka "matching
> push"?
>
> Most of the problems is what you are creating by using an unusual
> layout to name local branches differently from the remote
> counterpart.  You do not have to, and then all the problems you
> created with that layout goes away, without this patch.
>
> So, I am not sure if this is a good idea to begin with.  At least, I
> am not yet convinced.
>
> Thanks.
>