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

15 messages from 2026-10-17 to 2026-10-27. Participants: DonQuinleone, D. Ben Knoble, Harald Nordgren, Ben Knoble.
Thread: https://gitlist.dev/t/66562

## DonQuinleone, 2026-10-17 00:35

Subject: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref
Message-ID: <a8561fb7c2da446e7f7acc7e2a443991@donquinleone.com>
URL: https://gitlist.dev/e/a8561fb7c2da446e7f7acc7e2a443991%40donquinleone.com

```
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, 2026-10-22 12:46

Subject: Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref
Message-ID: <CALnO6CAsCvJRywkw0WpO1nEhL+yU2-r_4Z2AHdJch1m=NK8=TA@mail.gmail.com>
URL: https://gitlist.dev/e/CALnO6CAsCvJRywkw0WpO1nEhL%2ByU2-r_4Z2AHdJch1m%3DNK8%3DTA%40mail.gmail.com
In-Reply-To: <a8561fb7c2da446e7f7acc7e2a443991@donquinleone.com>

```
On Fri, Oct 16, 2026 at 8:41 PM DonQuinleone <don@donquinleone.com> wrote:
>
> 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!

> 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.

> 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).

> (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, 2026-10-22 13:43

Subject: Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref
Message-ID: <CAHwyqnWi3MCvAw-sNrn6k3ht1tpUfmNg18BAvEThKthen5Dwmw@mail.gmail.com>
URL: https://gitlist.dev/e/CAHwyqnWi3MCvAw-sNrn6k3ht1tpUfmNg18BAvEThKthen5Dwmw%40mail.gmail.com
In-Reply-To: <CALnO6CAsCvJRywkw0WpO1nEhL+yU2-r_4Z2AHdJch1m=NK8=TA@mail.gmail.com>

```
> 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


```

## Harald Nordgren, 2026-10-22 14:38

Subject: Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref
Message-ID: <CAHwyqnU-BEtOPdVbBXtuEYtFYuL3MqC9nUQeP_Puvq5bsoWEAQ@mail.gmail.com>
URL: https://gitlist.dev/e/CAHwyqnU-BEtOPdVbBXtuEYtFYuL3MqC9nUQeP_Puvq5bsoWEAQ%40mail.gmail.com
In-Reply-To: <CALnO6CAsCvJRywkw0WpO1nEhL+yU2-r_4Z2AHdJch1m=NK8=TA@mail.gmail.com>

```
> 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, 2026-10-22 17:14

Subject: Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref
Message-ID: <3EF4DA22-6739-46FA-8028-74EED08BB931@gmail.com>
URL: https://gitlist.dev/e/3EF4DA22-6739-46FA-8028-74EED08BB931%40gmail.com
In-Reply-To: <CAHwyqnU-BEtOPdVbBXtuEYtFYuL3MqC9nUQeP_Puvq5bsoWEAQ@mail.gmail.com>

```

> 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, 2026-10-22 17:52

Subject: Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref
Message-ID: <CAHwyqnWJOk9FCGkPi8yWOFq5vr-CMWNhn=wBAifx9Gfn+1bMzA@mail.gmail.com>
URL: https://gitlist.dev/e/CAHwyqnWJOk9FCGkPi8yWOFq5vr-CMWNhn%3DwBAifx9Gfn%2B1bMzA%40mail.gmail.com
In-Reply-To: <3EF4DA22-6739-46FA-8028-74EED08BB931@gmail.com>

```
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


Harald


```

## Harald Nordgren, 2026-10-22 17:53

Subject: Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref
Message-ID: <CAHwyqnWi6E=idoP2+1FdeEE4-o3D20xJfsc4Dutt6R30c===xQ@mail.gmail.com>
URL: https://gitlist.dev/e/CAHwyqnWi6E%3DidoP2%2B1FdeEE4-o3D20xJfsc4Dutt6R30c%3D%3D%3DxQ%40mail.gmail.com
In-Reply-To: <CAHwyqnWJOk9FCGkPi8yWOFq5vr-CMWNhn=wBAifx9Gfn+1bMzA@mail.gmail.com>

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


Harald


```

## D. Ben Knoble, 2026-10-24 13:14

Subject: Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref
Message-ID: <CALnO6CAxzo5gxpWkfjtvskTVjmWWD4oFE2QKyFMMo7JZUCkBmg@mail.gmail.com>
URL: https://gitlist.dev/e/CALnO6CAxzo5gxpWkfjtvskTVjmWWD4oFE2QKyFMMo7JZUCkBmg%40mail.gmail.com
In-Reply-To: <CAHwyqnWi3MCvAw-sNrn6k3ht1tpUfmNg18BAvEThKthen5Dwmw@mail.gmail.com>

```
On Thu, Oct 22, 2026 at 9:44 AM Harald Nordgren
<haraldnordgren@gmail.com> wrote:
>
> > 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.

> 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?

> 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).

> 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


```

## D. Ben Knoble, 2026-10-24 13:18

Subject: Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref
Message-ID: <CALnO6CAd62NqWMw66UT7mDuM71rcSBFidrr5f+PfR2jA9D9v=g@mail.gmail.com>
URL: https://gitlist.dev/e/CALnO6CAd62NqWMw66UT7mDuM71rcSBFidrr5f%2BPfR2jA9D9v%3Dg%40mail.gmail.com
In-Reply-To: <CAHwyqnWJOk9FCGkPi8yWOFq5vr-CMWNhn=wBAifx9Gfn+1bMzA@mail.gmail.com>

```
On Thu, Oct 22, 2026 at 1:52 PM Harald Nordgren
<haraldnordgren@gmail.com> wrote:
>
> 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


```

## D. Ben Knoble, 2026-10-24 13:35

Subject: Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref
Message-ID: <CALnO6CAAoMLZP4MBzgBa96RYMMReyxKXObb2JELqkBe=LBUVLg@mail.gmail.com>
URL: https://gitlist.dev/e/CALnO6CAAoMLZP4MBzgBa96RYMMReyxKXObb2JELqkBe%3DLBUVLg%40mail.gmail.com
In-Reply-To: <CAHwyqnWi6E=idoP2+1FdeEE4-o3D20xJfsc4Dutt6R30c===xQ@mail.gmail.com>

```
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


```

## Harald Nordgren, 2026-10-24 14:52

Subject: Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref
Message-ID: <CAHwyqnVV86Satk=_on=oG6ZVnSF5GdUWmpP0_wE74HRKGpKfSg@mail.gmail.com>
URL: https://gitlist.dev/e/CAHwyqnVV86Satk%3D_on%3DoG6ZVnSF5GdUWmpP0_wE74HRKGpKfSg%40mail.gmail.com
In-Reply-To: <CALnO6CAxzo5gxpWkfjtvskTVjmWWD4oFE2QKyFMMo7JZUCkBmg@mail.gmail.com>

```
> > 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!

> > 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 :)

> > 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.)

> 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, 2026-10-24 15:30

Subject: Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref
Message-ID: <CALnO6CCCHAG5UZi5w3znr5Uiruk8RvF2QZYu+QcVRzenyesu-w@mail.gmail.com>
URL: https://gitlist.dev/e/CALnO6CCCHAG5UZi5w3znr5Uiruk8RvF2QZYu%2BQcVRzenyesu-w%40mail.gmail.com
In-Reply-To: <CAHwyqnVV86Satk=_on=oG6ZVnSF5GdUWmpP0_wE74HRKGpKfSg@mail.gmail.com>

```
On Sat, Oct 24, 2026 at 10:52 AM Harald Nordgren
<haraldnordgren@gmail.com> wrote:
>
> > > 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 :/

> > > 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
;)

> > 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


```

## DonQuinleone, 2026-10-24 16:01

Subject: Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref
Message-ID: <ba149000e13634ffcc5dc51e4d584a56@donquinleone.com>
URL: https://gitlist.dev/e/ba149000e13634ffcc5dc51e4d584a56%40donquinleone.com
In-Reply-To: <CALnO6CAAoMLZP4MBzgBa96RYMMReyxKXObb2JELqkBe=LBUVLg@mail.gmail.com>

```
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, 2026-10-24 18:23

Subject: Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref
Message-ID: <CAHwyqnU5abc_KL-R__7G=PU8hGAaRGrXwZLuCkMJE0qoEFfKUQ@mail.gmail.com>
URL: https://gitlist.dev/e/CAHwyqnU5abc_KL-R__7G%3DPU8hGAaRGrXwZLuCkMJE0qoEFfKUQ%40mail.gmail.com
In-Reply-To: <ba149000e13634ffcc5dc51e4d584a56@donquinleone.com>

```
> 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, 2026-10-27 19:34

Subject: Re: [RFC] branch: delete gone-upstream branches only when proven merged into a named ref
Message-ID: <CALnO6CC+3shDYzX3ks0wk4YuxbsdCCTbKdgHO3fEwHEkN0yx7w@mail.gmail.com>
URL: https://gitlist.dev/e/CALnO6CC%2B3shDYzX3ks0wk4YuxbsdCCTbKdgHO3fEwHEkN0yx7w%40mail.gmail.com
In-Reply-To: <ba149000e13634ffcc5dc51e4d584a56@donquinleone.com>

```
[Liberally trimming some LLM-ish prose?]

On Sat, Oct 24, 2026 at 12:01 PM DonQuinleone <don@donquinleone.com> wrote:
>
> 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
;)

> 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


```
