threads / rfc / 66562

[RFC] branch: delete gone-upstream branches only when proven merged into a named ref

Subject: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref

## tl;dr

The RFC exposes a gap for the GitHub-style workflow of 'git push -u' and merge-commit PRs, and has turned into a discussion of triangular workflows and push.default. Read the story.

replies: 14people: 3as markdown or json

DonQuinleone· Oct 17, 2026, 00:35 UTC · lore
Hi all,

This is my first time posting to the list, so good to meet everyone, and thanks in advance for bearing with me.

I've just noticed that "git branch --delete-merged" is now available, and that it never deletes a topic in the workflow that hosting services (e.g. GitHub) encourage. Before writing a patch, I wanted to ask how the list might consider closing that gap.

In that workflow, the topic tracks and pushes to a branch of its own name; when the pull request is merged with a merge commit, the server deletes that branch. With master as of c51408889:

  $ git push -u origin topic
       ... merged on the server, and origin's topic deleted ...
  $ git fetch origin
  $ git branch --dry-run --delete-merged 'origin/*'
       ... spared, as pushing would update the upstream ...
  $ git fetch --prune origin
  $ git branch -vv
  * master 61e9886 [origin/master: behind 2] base
    topic  87d0c48 [origin/topic: gone] topic work
  $ git branch --dry-run --delete-merged 'origin/*'
       ... skipped, because the upstream is gone ...
  $ git merge-base --is-ancestor topic origin/master && echo merged
  merged

So the branch is provably merged, but at no point in this workflow will --delete-merged remove it. A script reproducing this is at the bottom.

From reading back through the archives, this is deliberate. When v7 of the series fell back to the remote's default branch for a gone upstream, Junio wrote [1]:

> If the upstream itself is gone, removing anything based on some other
> criteria cannot by definition a "safety check".

I agree that a vanished upstream proves nothing, so I would like to propose separating selection from proof:

"Upstream gone" may select a candidate, but it is never proof. The only proof is that the branch tip is reachable from a ref the user names explicitly, so nothing is inferred: neither HEAD, nor the remote's default branch.

I can see two possible shapes.
(A) A modifier on --delete-merged:
  $ git branch --delete-merged 'origin/*' --into origin/master

Branches whose upstream matches the pattern but no longer exists would become candidates, and would be deleted only if their tip is reachable from the named commit. check_branch_commit() would be handed that commit in place of HEAD, as suggested on v7 [1]. Branches whose upstream still exists would be judged exactly as today, and the worktree, stacked-branch and deleteMerged=false exclusions would still apply.

(B) Composable filters on -d:
  $ git branch --upstream-gone --merged=origin/master      # preview
  $ git branch -d --upstream-gone --merged=origin/master   # delete

--upstream-gone would be useful on its own for listing (today the usual approach is to grep "git branch -vv" for ": gone]"). But it turns -d into a second bulk-delete mode beside --delete-merged, and --merged defaults to HEAD when it comes last, so a forgotten argument would quietly bring back HEAD as the proxy.

I lean towards (A) because it is small and keeps every existing protection, but I'd rather settle the shape here than assume anything.

So:
 1. Is "selection is not proof" an acceptable basis for touching
    gone-upstream branches?
 2. (A), (B), or something else? If (A), is there a better name than
    --into (--merged-into?), and should it stay limited to branches
    whose upstream is gone?

I would leave squashing and rebasing out of scope, in keeping with --delete-merged staying "one stable and strict" operation [2]. I've Cc'd Harald, as this relates closely to his in-flight --delete-merged topics [3][4], and Phillip, who reviewed the series.

Thanks in advance. Look forward to hearing what people think.
~ Don

[1] https://lore.kernel.org/git/xmqq5x4sn393.fsf@gitster.g/ [2] https://lore.kernel.org/git/xmqqy0c21gq1.fsf@gitster.g/ [3] https://lore.kernel.org/git/pull.2428.v2.git.git.1791102886740.gitgitgadget@gmail.com/ [4] https://lore.kernel.org/git/94a6d23f8b96d4a07fb58c71f4a2f7dc4d3055bc.1791711665.git.gitgitgadget@gmail.com/

-- >8 --
#!/bin/sh
set -e
export GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_NOSYSTEM=1
export GIT_AUTHOR_NAME=A GIT_AUTHOR_EMAIL=a@example.com
export GIT_COMMITTER_NAME=C GIT_COMMITTER_EMAIL=c@example.com
cd "$(mktemp -d)"
git init -q --bare -b master origin.git
git clone -q origin.git work 2>/dev/null && cd work
git commit -q --allow-empty -m base && git push -q origin HEAD:master
git switch -q -c topic && git commit -q --allow-empty -m "topic work"
git push -q -u origin topic 2>/dev/null && git switch -q master
git clone -q ../origin.git ../server && (cd ../server &&
	git merge -q --no-ff -m "Merge topic" origin/topic &&
	git push -q origin master :topic)
echo "after fetch:";         git fetch -q
git branch --dry-run --delete-merged 'origin/*'
echo "after fetch --prune:"; git fetch -q --prune
git branch --dry-run --delete-merged 'origin/*'
git merge-base --is-ancestor topic origin/master && echo merged
D. Ben Knoble· Oct 22, 2026, 12:46 UTC · re: DonQuinleone · lore

Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref

On Fri, Oct 16, 2026 at 8:41 PM DonQuinleone <don@donquinleone.com> wrote:
Show 41 quoted lines
>
> Hi all,
>
> This is my first time posting to the list, so good to meet everyone,
> and thanks in advance for bearing with me.
>
> I've just noticed that "git branch --delete-merged" is now available,
> and that it never deletes a topic in the workflow that hosting
> services (e.g. GitHub) encourage. Before writing a patch, I wanted to
> ask how the list might consider closing that gap.
>
> In that workflow, the topic tracks and pushes to a branch of its own
> name; when the pull request is merged with a merge commit, the server
> deletes that branch. With master as of c51408889:
>
>   $ git push -u origin topic
>        ... merged on the server, and origin's topic deleted ...
>
>   $ git fetch origin
>   $ git branch --dry-run --delete-merged 'origin/*'
>        ... spared, as pushing would update the upstream ...
>
>   $ git fetch --prune origin
>   $ git branch -vv
>   * master 61e9886 [origin/master: behind 2] base
>     topic  87d0c48 [origin/topic: gone] topic work
>   $ git branch --dry-run --delete-merged 'origin/*'
>        ... skipped, because the upstream is gone ...
>   $ git merge-base --is-ancestor topic origin/master && echo merged
>   merged
>
> So the branch is provably merged, but at no point in this workflow
> will --delete-merged remove it. A script reproducing this is at the
> bottom.
>
> From reading back through the archives, this is deliberate. When v7
> of the series fell back to the remote's default branch for a gone
> upstream, Junio wrote [1]:
>
> > If the upstream itself is gone, removing anything based on some other
> > criteria cannot by definition a "safety check".

Hm. I had a hard time following the "--delete-merged" series, so this may come out of ignorance, but: we are asking Git to delete things merged into "origin/*"; I'm not sure why we'd need to consult "topic@{upstream}" to see that "topic" is merged into "origin/master" here, since there's a merge commit with "topic" as one of the parents?!

Ah, but the manual seems to contradict my (personal) "natural" reading of the command: "--delete-merged" actually deletes branches whose tip is reachable from their upstream (when that upstream matches the given pattern). So, phooey. In this case, if "topic@{upstream}" was "origin/master", though, "--delete-merged=origin/*" would work, no? Incidentally, I find it a shame that GitHub's documentation encourages a triangular workflow (whether or not there is a fork remote involved) without talking about how to configure Git to help you: fork or not, if you push to a topic branch but merge to another, it's extremely handy to use push.default=current or some variant so that

- @{upstream} is the place you'll merge
- @{push} is the place you push

and suddenly "git pull [--rebase]" does the right thing, "git status" (esp. with the new "status.compareBranches") can tell you where you are relative to both places of interest, etc.

IOW, "git push -u origin topic" makes upstream configuration very odd in the GitHub-ish workflow!

Show 7 quoted lines
> I agree that a vanished upstream proves nothing, so I would like to
> propose separating selection from proof:
>
> "Upstream gone" may select a candidate, but it is never proof. The
> only proof is that the branch tip is reachable from a ref the user
> names explicitly, so nothing is inferred: neither HEAD, nor the
> remote's default branch.

I'll refrain from commenting on whether we want to make "--delete-merged" delete a branch here or whether we need an additional mechanism for including topics whose upstream disappeared, but Git's CLI is already a bit notorious, so whatever interface we design should be composable.

Show 13 quoted lines
> I can see two possible shapes.
>
> (A) A modifier on --delete-merged:
>
>   $ git branch --delete-merged 'origin/*' --into origin/master
>
> Branches whose upstream matches the pattern but no longer exists would
> become candidates, and would be deleted only if their tip is reachable
> from the named commit. check_branch_commit() would be handed that
> commit in place of HEAD, as suggested on v7 [1]. Branches whose
> upstream still exists would be judged exactly as today, and the
> worktree, stacked-branch and deleteMerged=false exclusions would still
> apply.

A standalone modifier for another option makes the interface (IMO) complex; now we have to explain that "--into" only makes sense in some contexts (and add code to bail out).

I would much rather see more --option=value,value,value syntaxes, like
     git branch --delete-merged='origin/*,into:origin/master'

If we gain another form, we don't need new --options. We would also be able to say "--delete-merged=into:origin" and DWIM without any upstream configuration (or, with push.default=simple, even when upstream is just the place one pushed to).

Show 10 quoted lines
> (B) Composable filters on -d:
>
>   $ git branch --upstream-gone --merged=origin/master      # preview
>   $ git branch -d --upstream-gone --merged=origin/master   # delete
>
> --upstream-gone would be useful on its own for listing (today the
> usual approach is to grep "git branch -vv" for ": gone]"). But it
> turns -d into a second bulk-delete mode beside --delete-merged, and
> --merged defaults to HEAD when it comes last, so a forgotten argument
> would quietly bring back HEAD as the proxy.

In a world where we didn't have --delete-merged, this would have been the natural fit, I think. Imagine:

    git branch -d --merged-upstream=<pat>
    git branch -d --merged-into=<pat>

etc. Or even "--merged=upstream:<pat>,into:<pat>". Then we could also take some of the "--list" filters and make them apply to "-d". In the ambiguous case of a ref named, say, "--contains", we could use "--" to separate options from named branches to delete.

Harald Nordgren· Oct 22, 2026, 13:43 UTC · re: D. Ben Knoble · lore

Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref

Show 20 quoted lines
> Ah, but the manual seems to contradict my (personal) "natural" reading
> of the command: "--delete-merged" actually deletes branches whose tip
> is reachable from their upstream (when that upstream matches the given
> pattern). So, phooey. In this case, if "topic@{upstream}" was
> "origin/master", though, "--delete-merged=origin/*" would work, no?
> Incidentally, I find it a shame that GitHub's documentation encourages
> a triangular workflow (whether or not there is a fork remote involved)
> without talking about how to configure Git to help you: fork or not,
> if you push to a topic branch but merge to another, it's extremely
> handy to use push.default=current or some variant so that
>
> - @{upstream} is the place you'll merge
> - @{push} is the place you push
>
> and suddenly "git pull [--rebase]" does the right thing, "git status"
> (esp. with the new "status.compareBranches") can tell you where you
> are relative to both places of interest, etc.
>
> IOW, "git push -u origin topic" makes upstream configuration very odd
> in the GitHub-ish workflow!
Fully agree!

I would say most workflows are triangular on the underlying level, even if the developer is not aware of it. If you work with GitHub PRs or GitLab's MR, then you are engaging in a triangular workflow.

I picked up some important tricks for visualizing the triangular on this mailing list. But most of our users are not on the mailing list. But what we can and should do is to make git itself clearer, so they have a chance of intuiting it. I think for example that

    push.default=current
should likely be the default. And many people would have a better time with
    branch.autosetupmerge=inherit

which gives you upstream/master as @{u} from the beginning, and then you likely never abandon that if you are a regular GitHub user.

This is also why I feel strongly about this as default (https://lore.kernel.org/git/pull.2458.git.git.1792437798463.gitgitgadget@gmail.com/):

    status.comparebranches=@{upstream} @{push}

because it's confusing to switch tracking away from your "own branch" to upstream/master, if that means losing the waypoint of how things compare against @{push}.

Harald
D. Ben Knoble· Oct 24, 2026, 13:14 UTC · re: Harald Nordgren · lore

Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref

On Thu, Oct 22, 2026 at 9:44 AM Harald Nordgren <haraldnordgren@gmail.com> wrote:

Show 30 quoted lines
>
> > Ah, but the manual seems to contradict my (personal) "natural" reading
> > of the command: "--delete-merged" actually deletes branches whose tip
> > is reachable from their upstream (when that upstream matches the given
> > pattern). So, phooey. In this case, if "topic@{upstream}" was
> > "origin/master", though, "--delete-merged=origin/*" would work, no?
> > Incidentally, I find it a shame that GitHub's documentation encourages
> > a triangular workflow (whether or not there is a fork remote involved)
> > without talking about how to configure Git to help you: fork or not,
> > if you push to a topic branch but merge to another, it's extremely
> > handy to use push.default=current or some variant so that
> >
> > - @{upstream} is the place you'll merge
> > - @{push} is the place you push
> >
> > and suddenly "git pull [--rebase]" does the right thing, "git status"
> > (esp. with the new "status.compareBranches") can tell you where you
> > are relative to both places of interest, etc.
> >
> > IOW, "git push -u origin topic" makes upstream configuration very odd
> > in the GitHub-ish workflow!
>
> Fully agree!
>
> I would say most workflows are triangular on the underlying level,
> even if the developer is not aware of it. If you work with GitHub PRs
> or GitLab's MR, then you are engaging in a triangular workflow.
>
> I picked up some important tricks for visualizing the triangular on
> this mailing list. But most of our users are not on the mailing list.

Yep. Maybe I'll start writing a "triangular workflow" document à la Julia's work… going on the todo list, at any rate.

Show 6 quoted lines
> But what we can and should do is to make git itself clearer, so they
> have a chance of intuiting it. I think for example that
>
>     push.default=current
>
> should likely be the default.

IIUC, the last change in this area was controversial. I worry that changes here now would have to get through "scar tissue" (both of Git contributors *and* users). At any rate, it would probably want to be a major version release, and I understand it's probably too late to discuss flipping that in 3.0?

Show 6 quoted lines
> And many people would have a better time with
>
>     branch.autosetupmerge=inherit
>
> which gives you upstream/master as @{u} from the beginning, and then
> you likely never abandon that if you are a regular GitHub user.
Hm. Since I mostly do
    git switch -c topic origin

or similar, I'm ok with the default (=true). With inherit, the primary help is to folks who do

    git switch -c topic main

or something, right? But the documentation doesn't say what happens when inherit is used with a remote-tracking branch as a starting point (which has no upstream to copy from).

Show 8 quoted lines
> This is also why I feel strongly about this as default
> (https://lore.kernel.org/git/pull.2458.git.git.1792437798463.gitgitgadget@gmail.com/):
>
>     status.comparebranches=@{upstream} @{push}
>
> because it's confusing to switch tracking away from your "own branch"
> to upstream/master, if that means losing the waypoint of how things
> compare against @{push}.
Yeah, I'll try and reply in that thread shortly.
-- 
D. Ben Knoble
Harald Nordgren· Oct 24, 2026, 14:52 UTC · re: D. Ben Knoble · lore

Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref

Show 9 quoted lines
> > I would say most workflows are triangular on the underlying level,
> > even if the developer is not aware of it. If you work with GitHub PRs
> > or GitLab's MR, then you are engaging in a triangular workflow.
> >
> > I picked up some important tricks for visualizing the triangular on
> > this mailing list. But most of our users are not on the mailing list.
>
> Yep. Maybe I'll start writing a "triangular workflow" document à la
> Julia's work… going on the todo list, at any rate.
That would be cool!
Show 12 quoted lines
> > But what we can and should do is to make git itself clearer, so they
> > have a chance of intuiting it. I think for example that
> >
> >     push.default=current
> >
> > should likely be the default.
>
> IIUC, the last change in this area was controversial. I worry that
> changes here now would have to get through "scar tissue" (both of Git
> contributors *and* users). At any rate, it would probably want to be a
> major version release, and I understand it's probably too late to
> discuss flipping that in 3.0?
Would be interesting to switch to "current" as default for 3.0.

But I don't know all the history there. "Simple" does feel like a compromise in that it's not really good for anyone :)

Show 10 quoted lines
> > And many people would have a better time with
> >
> >     branch.autosetupmerge=inherit
> >
> > which gives you upstream/master as @{u} from the beginning, and then
> > you likely never abandon that if you are a regular GitHub user.
>
> Hm. Since I mostly do
>
>     git switch -c topic origin

Me too (or it least I used to before I started experimenting with inherit) although for currying purposes I always spell it

    git switch origin -c topic

since I want to have the most variable part last, so e.g. "git sw..." auto-completes by pressing the up key in zsh to give me almost the right thing and I can just erase and re-fill the last part of the command. (This whole paragraph is a complete side-note.)

Show 8 quoted lines
> or similar, I'm ok with the default (=true). With inherit, the primary
> help is to folks who do
>
>     git switch -c topic main
>
> or something, right? But the documentation doesn't say what happens
> when inherit is used with a remote-tracking branch as a starting point
> (which has no upstream to copy from).

It's simpler than that, since you can skip the "main" part, which by the way I don't think is well understood by regular users.

This is the beautiful part: since you start with a good upstream when cloning (origin/main) you never need to leave it, *and* you never need to even specify it when branching throughout the lifecycle of the repo.

Harald
D. Ben Knoble· Oct 24, 2026, 15:30 UTC · re: Harald Nordgren · lore

Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref

On Sat, Oct 24, 2026 at 10:52 AM Harald Nordgren <haraldnordgren@gmail.com> wrote:

Show 18 quoted lines
>
> > > But what we can and should do is to make git itself clearer, so they
> > > have a chance of intuiting it. I think for example that
> > >
> > >     push.default=current
> > >
> > > should likely be the default.
> >
> > IIUC, the last change in this area was controversial. I worry that
> > changes here now would have to get through "scar tissue" (both of Git
> > contributors *and* users). At any rate, it would probably want to be a
> > major version release, and I understand it's probably too late to
> > discuss flipping that in 3.0?
>
> Would be interesting to switch to "current" as default for 3.0.
>
> But I don't know all the history there. "Simple" does feel like a
> compromise in that it's not really good for anyone :)

I can certainly agree it doesn't seem that way to me! OTOH, it's being used by presumably most of our users today… so… "good" is perhaps a matter of how you define it ;)

You and I see "good" as "helping folks take advantage of all Git has to offer", while some of our users are content "as simple as possible without learning more that lets me get the job done." Neither is better than the other, so even if I too wish push.default=simple were not the default, I can't say it isn't good for anyone :/

Show 20 quoted lines
> > > And many people would have a better time with
> > >
> > >     branch.autosetupmerge=inherit
> > >
> > > which gives you upstream/master as @{u} from the beginning, and then
> > > you likely never abandon that if you are a regular GitHub user.
> >
> > Hm. Since I mostly do
> >
> >     git switch -c topic origin
>
> Me too (or it least I used to before I started experimenting with
> inherit) although for currying purposes I always spell it
>
>     git switch origin -c topic
>
> since I want to have the most variable part last, so e.g. "git sw..."
> auto-completes by pressing the up key in zsh to give me almost the
> right thing and I can just erase and re-fill the last part of the
> command. (This whole paragraph is a complete side-note.)

Continuing the tangent, then, that's now "git help cli" describes Git working, and one day someone might make things stricter and break you ;)

Show 11 quoted lines
> > or similar, I'm ok with the default (=true). With inherit, the primary
> > help is to folks who do
> >
> >     git switch -c topic main
> >
> > or something, right? But the documentation doesn't say what happens
> > when inherit is used with a remote-tracking branch as a starting point
> > (which has no upstream to copy from).
>
> It's simpler than that, since you can skip the "main" part, which by
> the way I don't think is well understood by regular users.

Ah, I also didn't understand that. But that only works if (a) you're already on a branch whose upstream is main, a reasonable assumption, and (b) you don't care if you have to type "git reset --hard @{upstream}" afterwards, right? If I am on some topic branch that's ahead of upstream, then my new branch is at the same commit, which is not usually what I want. In some projects and workflows that's a reasonable thing to do, though!

One advantage for me of specifying origin or w/e is that I get to start with a clean slate/known good starting point, since the reset happens automatically.

-- 
D. Ben Knoble
Harald Nordgren· Oct 22, 2026, 14:38 UTC · re: D. Ben Knoble · lore

Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref

> I would much rather see more --option=value,value,value syntaxes, like
>
>      git branch --delete-merged='origin/*,into:origin/master'
This feels completely chaotic to me and becomes a kitchen sink :)
Harald
Ben Knoble· Oct 22, 2026, 17:14 UTC · re: Harald Nordgren · lore

Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref

Show 9 quoted lines
> Le 22 oct. 2026 à 10:39, Harald Nordgren <haraldnordgren@gmail.com> a écrit :
> 
> 
>> 
>> I would much rather see more --option=value,value,value syntaxes, like
>> 
>>     git branch --delete-merged='origin/*,into:origin/master'
> 
> This feels completely chaotic to me and becomes a kitchen sink :)
But is it better or worse than the kitchen sink of
    git branch --delete-merged origin/* --into origin/master […]

? Hm. I suppose if you didn’t like commas, we could allow repeating the option to « stack » instead of replacing.

But I get the feeling that’s not what you took issue with ;)
Harald Nordgren· Oct 22, 2026, 17:52 UTC · re: Ben Knoble · lore

Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref

On Thu, Oct 22, 2026 at 7:14 PM Ben Knoble <ben.knoble@gmail.com> wrote:
Show 20 quoted lines
>
>
> > Le 22 oct. 2026 à 10:39, Harald Nordgren <haraldnordgren@gmail.com> a écrit :
> >
> > 
> >>
> >> I would much rather see more --option=value,value,value syntaxes, like
> >>
> >>     git branch --delete-merged='origin/*,into:origin/master'
> >
> > This feels completely chaotic to me and becomes a kitchen sink :)
>
> But is it better or worse than the kitchen sink of
>
>     git branch --delete-merged origin/* --into origin/master […]
>
> ? Hm. I suppose if you didn’t like commas, we could allow
> repeating the option to « stack » instead of replacing.
>
> But I get the feeling that’s not what you took issue with ;)
No, this is the part I take issue with:
    --delete-merged=into:origin/master
It feels akin to hacking some code into the arg like a
    find . -exec something
Harald
D. Ben Knoble· Oct 24, 2026, 13:35 UTC · re: Harald Nordgren · lore

Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref

On Thu, Oct 22, 2026 at 1:54 PM Harald Nordgren <haraldnordgren@gmail.com> wrote:

>
> Why do we need the `--into` at all?

This message trimmed so much context that I had to visit lore to see what it replied to…

…but I think you'll find the answer in the original mail, which discusses how --delete-merged works when the upstream branch is deleted (e.g., via GitHub's "automatically delete head branches" setting, which is useful to enable IMO). In that case, even though the branch was merged, the local topic is not a candidate for deletion (because we can't be sure about what happened to its upstream).

So the proposal is originally either
* add a modifier to --delete-merged that allows considering such topics
* add a modifier to "git branch --delete" for the same
To which I've suggested that either
* delete-merged should be allowed to work in this case, possibly via a
special syntax, modifier option, etc.
* branch --delete should be allowed to filter branches, in which case
we could even migrate some of --delete-merged into that form

In hindsight, an *even more composable* interface would have been to teach --list mode how to filter the appropriate merged branches (which we could then add to for this RFC) and encourage

    git branch --list [filters] | xargs git branch -d

possibly adding a -z option if needed (which my read of git-check-ref-format(1) suggests is unnecessary)? In which case --delete-merged could be something like

    git branch --list --merged-upstream=origin/main | xargs git branch -d

where --merged-upstream=<commit> lists all branches whose upstream configuration is reachable from <commit> (and I suppose you might need "-D" in some cases, hence the --delete-merged --dry-run form today, which would be "just omit the pipe to xargs" in this version). And the delete-merged branch filter would still work, since --list takes pattern arguments! Hm. I'm starting more and more to feel like this is a missed opportunity.

Rereading our docs for git-branch(1), I think what this RFC is looking for is
    git branch --list --merged=origin/main | xargs git branch -d

which should already list (and then delete) local branches whose tip is reachable from origin/main. And it would be sure nice if that combined with --delete-merged, but since they are separate forms, more work is needed. If we had the --merged-upstream filter, we'd simply do

    git branch --list --merged{,-upstream}=origin/main | xargs git branch -d
:)
-- 
D. Ben Knoble
DonQuinleone· Oct 24, 2026, 16:01 UTC · re: D. Ben Knoble · lore

Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref

Hi Ben, Harald,

Thanks both, this has been really helpful. I've tried each suggestion against the reproduction script with Git 2.56.0, and here's where I've got to.

D. Ben Knoble wrote:
> In this case, if "topic@{upstream}" was "origin/master", though,
> "--delete-merged=origin/*" would work, no?

Yes. With push.default=current, "git switch -c topic origin/master" and a plain "git push origin topic", the dry run offers to delete topic once the pull request is merged, with no code change at all. So the gap is only for people who follow the hosting services' advice and run "git push -u", which points @{upstream} at the topic's own remote branch. That's the setup I'd hoped to help, and I suspect it's a common one, but I agree the better long-term fix there is teaching the triangular setup. A document like the one you mentioned would be very welcome.

Harald Nordgren wrote:
> Why do we need the `--into` at all?

Ben has covered it, but in short: once the upstream is gone there is nothing left for --delete-merged to check against, and Junio ruled out Git choosing a substitute (HEAD, or the remote's default branch). So the commit has to come from the user, and --into was simply a way to name it.

D. Ben Knoble wrote:
> Rereading our docs for git-branch(1), I think what this RFC is
> looking for is
> >     git branch --list --merged=origin/main | xargs git branch -d

That was my hope too, but it doesn't quite get there in the reproduction:

  $ git branch --list --merged=origin/master | xargs git branch -d
  error: branch '*' not found
  error: cannot delete branch 'master' used by worktree at '...'
  error: the branch 'topic' is not fully merged

The first two are just the listing format, and for-each-ref would avoid them. The third is the interesting one. "git branch -d" checks topic against its upstream, which is gone, so it falls back to HEAD, and master is behind origin/master. The commit that selected the branch is not the commit that checks it, so the proof is lost at the pipe. Only -D gets through, and that drops the check altogether. (The listing also picks up master itself, and would pick up any branch that has been created but not yet committed to.)

To me that points to the shape you sketched for (B), with one change: when -d is given list filters, the --merged commit is the proof as well as a filter.

  $ git branch --upstream-gone --merged=origin/master      # list
  $ git branch -d --upstream-gone --merged=origin/master   # delete
In the -d form:
 - --merged needs an explicit commit; there is no HEAD default, so
   nothing is inferred;
 - each selected branch is deleted only if its tip is reachable from
   that commit, in place of the usual upstream-or-HEAD check;
 - a branch checked out in any worktree is still refused, and
   branch.<name>.deleteMerged=false would be honoured;
 - --upstream-gone and the existing --forked narrow the selection, so
   it doesn't sweep up master or a branch that hasn't been pushed yet.

"git branch -d --merged=..." is rejected with the usage message today, so this adds a form rather than changing one, and --delete-merged stays exactly as it is. In the RFC I worried that this would make -d a second bulk-delete mode, but given your point about composability I now think that's the better trade. It avoids both an option that only means something next to another option and sub-values packed into one argument, which I hope answers both of your concerns. I'd welcome being told otherwise.

So, updating my two questions:
 1. Is "selection is not proof" an acceptable basis for deleting
    gone-upstream branches at all, when the proof is a commit the user
    names explicitly?
 2. Ben, Harald: is a filtered -d, with an explicit --merged as the
    proof, the shape you'd want? If so, I'd start with --upstream-gone
    as a listing filter on its own, since it's useful without the
    delete half (it replaces grepping "git branch -vv" for ": gone]"),
    and follow with the -d part as a second patch.
Thanks again,
~ Don
Harald Nordgren· Oct 24, 2026, 18:23 UTC · re: DonQuinleone · lore

Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref

Show 13 quoted lines
> D. Ben Knoble wrote:
> > In this case, if "topic@{upstream}" was "origin/master", though,
> > "--delete-merged=origin/*" would work, no?
>
> Yes. With push.default=current, "git switch -c topic origin/master"
> and a plain "git push origin topic", the dry run offers to delete topic
> once the pull request is merged, with no code change at all. So the gap
> is only for people who follow the hosting services' advice and run
> "git push -u", which points @{upstream} at the topic's own remote
> branch. That's the setup I'd hoped to help, and I suspect it's a common
> one, but I agree the better long-term fix there is teaching the
> triangular setup. A document like the one you mentioned would be very
> welcome.

FWIW, I still regard "squash merge" as part of a triangular workflow, since GitHub's PRs are inherently triangular.

Harald
D. Ben Knoble· Oct 27, 2026, 19:34 UTC · re: DonQuinleone · lore

Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref

[Liberally trimming some LLM-ish prose?]
On Sat, Oct 24, 2026 at 12:01 PM DonQuinleone <don@donquinleone.com> wrote:
Show 19 quoted lines
>
> Hi Ben, Harald,
>
> Thanks both, this has been really helpful. I've tried each suggestion
> against the reproduction script with Git 2.56.0, and here's where I've
> got to.
>
> D. Ben Knoble wrote:
> > In this case, if "topic@{upstream}" was "origin/master", though,
> > "--delete-merged=origin/*" would work, no?
>
> Yes. With push.default=current, "git switch -c topic origin/master"
> and "git push origin topic", the dry run offers to delete topic
> once the pull request is merged. So the gap
> is only for people who follow the hosting services' advice and run
> "git push -u". That's the setup I'd hoped to help, and I suspect it's a common
> one, but I agree the better long-term fix there is teaching the
> triangular setup. A document like the one you mentioned would be very
> welcome.

Yeah… I'm not too sure about the "push -u" setup, which only really works when you push to/pull from the same place. I personally want to spend my effort weaning folks off that model for triangular workflows ;)

Show 13 quoted lines
> D. Ben Knoble wrote:
> > Rereading our docs for git-branch(1), I think what this RFC is
> > looking for is
> >
> >     git branch --list --merged=origin/main | xargs git branch -d
>
> That was my hope too, but it doesn't quite get there in the
> reproduction:
>
>    $ git branch --list --merged=origin/master | xargs git branch -d
>    error: branch '*' not found
>    error: cannot delete branch 'master' used by worktree at '...'
>    error: the branch 'topic' is not fully merged

Yeah, I missed that the default output format "git branch --list" doesn't course-correct for being machine readable. But!

We can do
    git branch --list --format='%(refname:lstrip=2)' [filters] | xargs …
pretty easily!
> "git branch -d" checks topic
> against its upstream, which is gone, so it falls back to HEAD, and
> master is behind origin/master. Only
> -D [works], and that drops the check altogether.

Oh, that's interesting, I didn't know that about the deletion checks. Still, one can easily dry-run (no xargs) and then -D if needed, I suppose?

Not the best overall experience, but fairly composable, and something that could be built in to Git over time perhaps? idk.

> (The listing also
> picks up master itself, and would pick up any branch that has been
> created but not yet committed to.)

Ah, yeah. That's a bummer, and the only things I can think of are to explicitly omit it:

    | grep -v "^$(git branch --show-current)\$" | xargs …

or to simply "let it go" (even with -D Git refuses to delete the currently checked out branch). But that's a bit noisy.

> To me that points to the shape you sketched for (B), with one change:
> when -d is given list filters, the --merged commit is the proof as well
> as a filter.

At that point, I would lean towards teaching "-d" the same filters as the rest of "git branch --list" (and possibly additional ones, like --upstream-gone, if needed). That might involve some patches to make the filtering logic shareable between the 2, teaching "-d" about them, and then extending the set of filters?

Just a thought.
-- 
D. Ben Knoble
D. Ben Knoble· Oct 24, 2026, 13:18 UTC · re: Harald Nordgren · lore

Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref

On Thu, Oct 22, 2026 at 1:52 PM Harald Nordgren <haraldnordgren@gmail.com> wrote:

Show 27 quoted lines
>
> On Thu, Oct 22, 2026 at 7:14 PM Ben Knoble <ben.knoble@gmail.com> wrote:
> >
> > > Le 22 oct. 2026 à 10:39, Harald Nordgren <haraldnordgren@gmail.com> a écrit :
> > >>
> > >> I would much rather see more --option=value,value,value syntaxes, like
> > >>
> > >>     git branch --delete-merged='origin/*,into:origin/master'
> > >
> > > This feels completely chaotic to me and becomes a kitchen sink :)
> >
> > But is it better or worse than the kitchen sink of
> >
> >     git branch --delete-merged origin/* --into origin/master […]
> >
> > ? Hm. I suppose if you didn’t like commas, we could allow
> > repeating the option to « stack » instead of replacing.
> >
> > But I get the feeling that’s not what you took issue with ;)
>
> No, this is the part I take issue with:
>
>     --delete-merged=into:origin/master
>
> It feels akin to hacking some code into the arg like a
>
>     find . -exec something

Well, I find it more composable than tacking on additional modifiers via --long-options (which incidentally make the synopsis more complicated, and add lots of "this option only makes sense in this context" checks)---that "context-sensitive" nature seems to me to make our interface quite a bit more confusing. See the "INCOMPATIBLE OPTIONS" section of git-rebase, for example!

-- 
D. Ben Knoble

← back to recent threads