Re: [PATCH] checkout: add remoteBranchTemplate config for DWIM branch names
- From
- pasteley <ceasebeing@gmail.com>
- Date
- Dec 22, 2025, 18:27 UTC
- Message-ID
- <7246f693-2047-4218-8103-8143e01032f0@gmail.com>
- In-Reply-To
- <xmqqtsxjruwi.fsf@gitster.g>
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).
Show 6 quoted lines
> 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:
Show 44 quoted lines
> "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. >