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" [off-list ref] writes:

quoted

From: pasteley <redacted>

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.