Re: [PATCH v12 4/6] branch: add --prune-merged <branch>

[Phillip Wood <phillip.wood123@gmail.com>]

Hi Harald

On 03/06/2026 10:04, Harald Nordgren via GitGitGadget wrote:
> From: Harald Nordgren <haraldnordgren@gmail.com>
> 
> 	git branch --prune-merged <branch>...

I'm not sure that synopsis is correct anymore as you need to repeat 
"--prune-merged". As --prune-merged now takes an argument there is no 
reason to forbid positional arguments so I think we should support

	git branch --prune-merged origin/master 'feature*'

to delete all the branches beginning with "feature" that have the 
upstream "origin/master" and have been merged.

I wonder about the name - the other options that delete branches are 
called "delete", not "prune". Also "--prune-merged" does not delete the 
branches listed by "--merged" so maybe "--delete-forked" would be better?

I've not commented in detail on the code as it will need to change a bit 
once we match on full refnames and do the filtering in 
apply_ref_filter() but I think the basics are sound.

I'll stop here - I did quickly scan the next two patches and they both 
looked like sensible ideas.

Thanks

Phillip

> deletes the local branches that "--forked <branch>" would list,
> restricted to those whose tip is reachable from their configured
> upstream: the work has already landed on the upstream they track,
> so the local copy is no longer needed.
> 
> Reachability is read from local refs; nothing is fetched. Users
> who want fresh upstream refs run "git fetch" first.
> 
> Three classes of branches are spared:
> 
>    * any branch checked out in any worktree;
>    * any branch whose upstream no longer resolves locally (its
>      disappearance is not, on its own, evidence of integration);
>    * any branch whose push destination equals its upstream
>      (<branch>@{push} == <branch>@{upstream}). Such a branch
>      cannot be distinguished from a freshly pulled trunk that
>      just looks "fully merged", e.g. local "main" tracking and
>      pushing to "origin/main" right after a pull. Only branches
>      that push somewhere other than their upstream (typically
>      topics in a fork-based workflow) are treated as candidates.
> 
> Deletion goes through the existing delete_branches() in warn-only
> mode and with the HEAD-fallback disabled: a branch that is not
> yet fully merged to its upstream is reported as a one-line warning
> and skipped, so a single un-mergeable topic does not abort the
> whole sweep. We only act on upstream-merged status.
> 
> Signed-off-by: Harald Nordgren <haraldnordgren@gmail.com>
> ---
>   Documentation/git-branch.adoc |  23 +++++
>   builtin/branch.c              | 117 +++++++++++++++++++--
>   t/t3200-branch.sh             | 188 ++++++++++++++++++++++++++++++++++
>   3 files changed, 318 insertions(+), 10 deletions(-)
> 
> diff --git a/Documentation/git-branch.adoc b/Documentation/git-branch.adoc
> index 8002d7f38c..f7942fcd7d 100644
> --- a/Documentation/git-branch.adoc
> +++ b/Documentation/git-branch.adoc
> @@ -25,6 +25,7 @@ git branch (-m|-M) [<old-branch>] <new-branch>
>   git branch (-c|-C) [<old-branch>] <new-branch>
>   git branch (-d|-D) [-r] <branch-name>...
>   git branch --edit-description [<branch-name>]
> +git branch (--prune-merged <branch>)...
>   
>   DESCRIPTION
>   -----------
> @@ -206,6 +207,28 @@ This option is only applicable in non-verbose mode.
>   	`master`) or a shell-style glob (e.g. `'origin/*'`). The
>   	option can be repeated to widen the filter.
>   
> +`--prune-merged <branch>`::
> +	Delete the local branches that `--forked` would list for the
> +	same _<branch>_, but only those whose tip is reachable from
> +	their configured upstream. In other words, the work on the
> +	branch has already landed on the upstream it tracks, so the
> +	local copy is no longer needed. May be given more than once to
> +	union the matches; positional arguments are not accepted.
> ++
> +Reachability is checked against whatever the upstream refs say
> +locally; nothing is fetched. Run `git fetch` first if you want
> +the upstream refs refreshed.
> ++
> +A branch is left alone if any of the following holds:
> +its upstream no longer resolves locally; it is checked out in any
> +worktree; or its push destination (`<branch>@{push}`) equals its
> +upstream (`<branch>@{upstream}`), so it cannot be distinguished
> +from a freshly pulled trunk that just looks "fully merged".
> ++
> +Branches refused by the "fully merged" safety check are listed as
> +warnings and skipped; pass them to `git branch -D` explicitly if
> +you want them gone.
> +
>   `-v`::
>   `-vv`::
>   `--verbose`::
> diff --git a/builtin/branch.c b/builtin/branch.c
> index 09afdd9257..736480b002 100644
> --- a/builtin/branch.c
> +++ b/builtin/branch.c
> @@ -39,6 +39,7 @@ static const char * const builtin_branch_usage[] = {
>   	N_("git branch [<options>] (-c | -C) [<old-branch>] <new-branch>"),
>   	N_("git branch [<options>] [-r | -a] [--points-at]"),
>   	N_("git branch [<options>] [-r | -a] [--format]"),
> +	N_("git branch [<options>] (--prune-merged <branch>)..."),
>   	NULL
>   };
>   
> @@ -782,17 +783,13 @@ static int upstream_matches(const char *short_upstream,
>   	return 0;
>   }
>   
> -static int branch_upstream_matches(const char *full_refname,
> +static int branch_upstream_matches(const char *short_branch_name,
>   				   const struct upstream_pattern *patterns,
>   				   size_t nr_patterns)
>   {
> -	const char *short_name;
> -	struct branch *branch;
> +	struct branch *branch = branch_get(short_branch_name);
>   	const char *upstream;
>   
> -	if (!skip_prefix(full_refname, "refs/heads/", &short_name))
> -		return 0;
> -	branch = branch_get(short_name);
>   	if (!branch)
>   		return 0;
>   	upstream = branch_get_upstream(branch, NULL);
> @@ -813,8 +810,9 @@ static void filter_array_by_forked(struct ref_array *array,
>   
>   	for (i = 0; i < array->nr; i++) {
>   		struct ref_array_item *item = array->items[i];
> -		if (branch_upstream_matches(item->refname,
> -					    patterns, nr_patterns))
> +		const char *short_name;
> +		if (skip_prefix(item->refname, "refs/heads/", &short_name) &&
> +		    branch_upstream_matches(short_name, patterns, nr_patterns))
>   			array->items[kept++] = item;
>   		else
>   			free_ref_array_item(item);
> @@ -824,6 +822,94 @@ static void filter_array_by_forked(struct ref_array *array,
>   	upstream_pattern_list_clear(patterns, nr_patterns);
>   }
>   
> +struct forked_cb {
> +	const struct upstream_pattern *patterns;
> +	size_t nr_patterns;
> +	struct string_list *out;
> +};
> +
> +static int collect_forked_branch(const struct reference *ref, void *cb_data)
> +{
> +	struct forked_cb *cb = cb_data;
> +
> +	if (ref->flags & REF_ISSYMREF)
> +		return 0;
> +	if (branch_upstream_matches(ref->name, cb->patterns, cb->nr_patterns))
> +		string_list_append(cb->out, ref->name);
> +	return 0;
> +}
> +
> +static void collect_forked_set(const struct string_list *upstreams,
> +			       struct string_list *out)
> +{
> +	struct upstream_pattern *patterns = NULL;
> +	size_t nr_patterns = 0;
> +	struct forked_cb cb;
> +
> +	parse_forked_args(upstreams, &patterns, &nr_patterns);
> +	cb.patterns = patterns;
> +	cb.nr_patterns = nr_patterns;
> +	cb.out = out;
> +
> +	refs_for_each_branch_ref(get_main_ref_store(the_repository),
> +				 collect_forked_branch, &cb);
> +
> +	string_list_sort(out);
> +
> +	upstream_pattern_list_clear(patterns, nr_patterns);
> +}
> +
> +static int prune_merged_branches(const struct string_list *upstreams,
> +				 int quiet)
> +{
> +	struct ref_store *refs = get_main_ref_store(the_repository);
> +	struct string_list candidates = STRING_LIST_INIT_DUP;
> +	struct strvec deletable = STRVEC_INIT;
> +	struct string_list_item *item;
> +	int ret = 0;
> +
> +	if (!upstreams->nr)
> +		die(_("--prune-merged requires at least one <branch>"));
> +
> +	collect_forked_set(upstreams, &candidates);
> +
> +	for_each_string_list_item(item, &candidates) {
> +		const char *short_name = item->string;
> +		struct branch *branch = branch_get(short_name);
> +		const char *upstream, *push;
> +		struct strbuf full = STRBUF_INIT;
> +		int skip;
> +
> +		strbuf_addf(&full, "refs/heads/%s", short_name);
> +		skip = !!branch_checked_out(full.buf);
> +		strbuf_release(&full);
> +		if (skip)
> +			continue;
> +
> +		upstream = branch ? branch_get_upstream(branch, NULL) : NULL;
> +		if (!upstream || !refs_ref_exists(refs, upstream))
> +			continue;
> +		push = branch ? branch_get_push(branch, NULL) : NULL;
> +		if (!push || !strcmp(push, upstream))
> +			continue;
> +
> +		strvec_push(&deletable, short_name);
> +	}
> +
> +	if (deletable.nr)
> +		ret = delete_branches(deletable.nr, deletable.v,
> +				      0, /* force */
> +				      FILTER_REFS_BRANCHES,
> +				      quiet,
> +				      1, /* warn_only */
> +				      1, /* no_head_fallback */
> +				      0  /* dry_run */);
> +
> +	strvec_clear(&deletable);
> +	string_list_clear(&candidates, 0);
> +	return ret;
> +}
> +
>   static GIT_PATH_FUNC(edit_description, "EDIT_DESCRIPTION")
>   
>   static int edit_branch_description(const char *branch_name)
> @@ -866,6 +952,7 @@ int cmd_branch(int argc,
>   	int delete = 0, rename = 0, copy = 0, list = 0,
>   	    unset_upstream = 0, show_current = 0, edit_description = 0;
>   	struct string_list forked_upstreams = STRING_LIST_INIT_DUP;
> +	struct string_list prune_merged_upstreams = STRING_LIST_INIT_DUP;
>   	const char *new_upstream = NULL;
>   	int noncreate_actions = 0;
>   	/* possible options */
> @@ -921,6 +1008,8 @@ int cmd_branch(int argc,
>   			 N_("edit the description for the branch")),
>   		OPT_STRING_LIST(0, "forked", &forked_upstreams, N_("branch"),
>   			N_("list local branches whose upstream matches <branch> (repeatable)")),
> +		OPT_STRING_LIST(0, "prune-merged", &prune_merged_upstreams, N_("branch"),
> +			N_("delete local branches whose upstream matches <branch> and is merged (repeatable)")),
>   		OPT__FORCE(&force, N_("force creation, move/rename, deletion"), PARSE_OPT_NOCOMPLETE),
>   		OPT_MERGED(&filter, N_("print only branches that are merged")),
>   		OPT_NO_MERGED(&filter, N_("print only branches that are not merged")),
> @@ -965,7 +1054,8 @@ int cmd_branch(int argc,
>   			     0);
>   
>   	if (!delete && !rename && !copy && !edit_description && !new_upstream &&
> -	    !show_current && !unset_upstream && argc == 0)
> +	    !show_current && !unset_upstream && !prune_merged_upstreams.nr &&
> +	    argc == 0)
>   		list = 1;
>   
>   	if (filter.with_commit || filter.no_commit ||
> @@ -975,7 +1065,7 @@ int cmd_branch(int argc,
>   
>   	noncreate_actions = !!delete + !!rename + !!copy + !!new_upstream +
>   			    !!show_current + !!list + !!edit_description +
> -			    !!unset_upstream;
> +			    !!unset_upstream + !!prune_merged_upstreams.nr;
>   	if (noncreate_actions > 1)
>   		usage_with_options(builtin_branch_usage, options);
>   
> @@ -1016,6 +1106,12 @@ int cmd_branch(int argc,
>   		ret = delete_branches(argc, argv, delete > 1, filter.kind,
>   				      quiet, 0, 0, 0);
>   		goto out;
> +	} else if (prune_merged_upstreams.nr) {
> +		if (argc)
> +			die(_("--prune-merged does not take positional arguments; "
> +			      "repeat --prune-merged for each <branch>"));
> +		ret = prune_merged_branches(&prune_merged_upstreams, quiet);
> +		goto out;
>   	} else if (show_current) {
>   		print_current_branch_name();
>   		ret = 0;
> @@ -1178,5 +1274,6 @@ int cmd_branch(int argc,
>   out:
>   	string_list_clear(&sorting_options, 0);
>   	string_list_clear(&forked_upstreams, 0);
> +	string_list_clear(&prune_merged_upstreams, 0);
>   	return ret;
>   }
> diff --git a/t/t3200-branch.sh b/t/t3200-branch.sh
> index 4e7deddc04..beb86987ad 100755
> --- a/t/t3200-branch.sh
> +++ b/t/t3200-branch.sh
> @@ -1809,4 +1809,192 @@ test_expect_success '--forked requires a value' '
>   	test_grep "requires a value" err
>   '
>   
> +test_expect_success '--prune-merged: setup' '
> +	test_create_repo pm-upstream &&
> +	test_commit -C pm-upstream base &&
> +	git -C pm-upstream checkout -b next &&
> +	test_commit -C pm-upstream one-commit &&
> +	test_commit -C pm-upstream two-commit &&
> +	git -C pm-upstream branch one HEAD~ &&
> +	git -C pm-upstream branch two HEAD &&
> +	git -C pm-upstream branch wip main &&
> +	git -C pm-upstream checkout main &&
> +	test_create_repo pm-fork
> +'
> +
> +test_expect_success '--prune-merged deletes branches integrated into upstream' '
> +	test_when_finished "rm -rf pm-merged" &&
> +	git clone pm-upstream pm-merged &&
> +	git -C pm-merged remote add fork ../pm-fork &&
> +	test_config -C pm-merged remote.pushDefault fork &&
> +	test_config -C pm-merged push.default current &&
> +	git -C pm-merged branch one one-commit &&
> +	git -C pm-merged branch --set-upstream-to=origin/next one &&
> +	git -C pm-merged branch two two-commit &&
> +	git -C pm-merged branch --set-upstream-to=origin/next two &&
> +
> +	git -C pm-merged branch --prune-merged "origin/*" &&
> +
> +	test_must_fail git -C pm-merged rev-parse --verify refs/heads/one &&
> +	test_must_fail git -C pm-merged rev-parse --verify refs/heads/two
> +'
> +
> +test_expect_success '--prune-merged accepts a literal upstream' '
> +	test_when_finished "rm -rf pm-literal" &&
> +	git clone pm-upstream pm-literal &&
> +	git -C pm-literal remote add fork ../pm-fork &&
> +	test_config -C pm-literal remote.pushDefault fork &&
> +	test_config -C pm-literal push.default current &&
> +	git -C pm-literal branch one one-commit &&
> +	git -C pm-literal branch --set-upstream-to=origin/next one &&
> +
> +	git -C pm-literal branch --prune-merged origin/next &&
> +
> +	test_must_fail git -C pm-literal rev-parse --verify refs/heads/one
> +'
> +
> +test_expect_success '--prune-merged unions multiple <branch> arguments' '
> +	test_when_finished "rm -rf pm-union" &&
> +	git clone pm-upstream pm-union &&
> +	git -C pm-union remote add fork ../pm-fork &&
> +	test_config -C pm-union remote.pushDefault fork &&
> +	test_config -C pm-union push.default current &&
> +	git -C pm-union branch one one-commit &&
> +	git -C pm-union branch --set-upstream-to=origin/next one &&
> +	git -C pm-union branch two base &&
> +	git -C pm-union branch --set-upstream-to=origin/main two &&
> +	git -C pm-union checkout --detach &&
> +
> +	git -C pm-union branch --prune-merged origin/next --prune-merged origin/main &&
> +
> +	test_must_fail git -C pm-union rev-parse --verify refs/heads/one &&
> +	test_must_fail git -C pm-union rev-parse --verify refs/heads/two
> +'
> +
> +test_expect_success '--prune-merged accepts a local upstream' '
> +	test_when_finished "rm -rf pm-local" &&
> +	git clone pm-upstream pm-local &&
> +	git -C pm-local remote add fork ../pm-fork &&
> +	test_config -C pm-local remote.pushDefault fork &&
> +	test_config -C pm-local push.default current &&
> +	git -C pm-local checkout -b trunk &&
> +	git -C pm-local branch one one-commit &&
> +	git -C pm-local branch --set-upstream-to=trunk one &&
> +	git -C pm-local merge --ff-only one-commit &&
> +
> +	git -C pm-local branch --prune-merged trunk &&
> +
> +	test_must_fail git -C pm-local rev-parse --verify refs/heads/one
> +'
> +
> +test_expect_success '--prune-merged warns instead of erroring on un-integrated commits' '
> +	test_when_finished "rm -rf pm-unmerged" &&
> +	git clone pm-upstream pm-unmerged &&
> +	git -C pm-unmerged remote add fork ../pm-fork &&
> +	test_config -C pm-unmerged remote.pushDefault fork &&
> +	test_config -C pm-unmerged push.default current &&
> +	git -C pm-unmerged checkout -b wip origin/wip &&
> +	git -C pm-unmerged branch --set-upstream-to=origin/next wip &&
> +	test_commit -C pm-unmerged local-only &&
> +	git -C pm-unmerged checkout - &&
> +
> +	git -C pm-unmerged branch --prune-merged "origin/*" 2>err &&
> +	test_grep "not fully merged" err &&
> +	test_grep ! "If you are sure you want to delete it" err &&
> +	git -C pm-unmerged rev-parse --verify refs/heads/wip
> +'
> +
> +test_expect_success '--prune-merged is silent about not-merged-to-HEAD' '
> +	test_when_finished "rm -rf pm-nohead" &&
> +	git clone pm-upstream pm-nohead &&
> +	git -C pm-nohead remote add fork ../pm-fork &&
> +	test_config -C pm-nohead remote.pushDefault fork &&
> +	test_config -C pm-nohead push.default current &&
> +	git -C pm-nohead branch topic one-commit &&
> +	git -C pm-nohead branch --set-upstream-to=origin/next topic &&
> +
> +	git -C pm-nohead branch --prune-merged "origin/*" 2>err &&
> +
> +	test_grep ! "not yet merged to HEAD" err &&
> +	test_must_fail git -C pm-nohead rev-parse --verify refs/heads/topic
> +'
> +
> +test_expect_success '--prune-merged skips branches whose upstream is gone' '
> +	test_when_finished "rm -rf pm-upstream-gone" &&
> +	git clone pm-upstream pm-upstream-gone &&
> +	git -C pm-upstream-gone remote add fork ../pm-fork &&
> +	test_config -C pm-upstream-gone remote.pushDefault fork &&
> +	test_config -C pm-upstream-gone push.default current &&
> +	git -C pm-upstream-gone branch one one-commit &&
> +	git -C pm-upstream-gone branch --set-upstream-to=origin/next one &&
> +
> +	git -C pm-upstream-gone update-ref -d refs/remotes/origin/next &&
> +	git -C pm-upstream-gone branch --prune-merged "origin/*" &&
> +
> +	git -C pm-upstream-gone rev-parse --verify refs/heads/one
> +'
> +
> +test_expect_success '--prune-merged never deletes the checked-out branch' '
> +	test_when_finished "rm -rf pm-head" &&
> +	git clone pm-upstream pm-head &&
> +	git -C pm-head remote add fork ../pm-fork &&
> +	test_config -C pm-head remote.pushDefault fork &&
> +	test_config -C pm-head push.default current &&
> +	git -C pm-head checkout -b one one-commit &&
> +	git -C pm-head branch --set-upstream-to=origin/next one &&
> +
> +	git -C pm-head branch --prune-merged "origin/*" &&
> +
> +	git -C pm-head rev-parse --verify refs/heads/one
> +'
> +
> +test_expect_success '--prune-merged spares branches that push back to their upstream' '
> +	test_when_finished "rm -rf pm-push-eq" &&
> +	git clone pm-upstream pm-push-eq &&
> +	git -C pm-push-eq checkout --detach &&
> +
> +	git -C pm-push-eq branch --prune-merged "origin/*" &&
> +
> +	git -C pm-push-eq rev-parse --verify refs/heads/main
> +'
> +
> +test_expect_success '--prune-merged spares a per-branch pushRemote==upstream remote' '
> +	test_when_finished "rm -rf pm-push-branch" &&
> +	git clone pm-upstream pm-push-branch &&
> +	git -C pm-push-branch remote add fork ../pm-fork &&
> +	test_config -C pm-push-branch remote.pushDefault fork &&
> +	test_config -C pm-push-branch push.default current &&
> +	test_config -C pm-push-branch branch.main.pushRemote origin &&
> +	git -C pm-push-branch checkout --detach &&
> +
> +	git -C pm-push-branch branch --prune-merged "origin/*" &&
> +
> +	git -C pm-push-branch rev-parse --verify refs/heads/main
> +'
> +
> +test_expect_success '--prune-merged prunes when @{push} differs from @{upstream}' '
> +	test_when_finished "rm -rf pm-push-diff" &&
> +	git clone pm-upstream pm-push-diff &&
> +	git -C pm-push-diff remote add fork ../pm-fork &&
> +	test_config -C pm-push-diff remote.pushDefault fork &&
> +	test_config -C pm-push-diff push.default current &&
> +	git -C pm-push-diff branch topic one-commit &&
> +	git -C pm-push-diff branch --set-upstream-to=origin/next topic &&
> +	git -C pm-push-diff checkout --detach &&
> +
> +	git -C pm-push-diff branch --prune-merged "origin/*" &&
> +
> +	test_must_fail git -C pm-push-diff rev-parse --verify refs/heads/topic
> +'
> +
> +test_expect_success '--prune-merged requires a value' '
> +	test_must_fail git -C forked branch --prune-merged 2>err &&
> +	test_grep "requires a value" err
> +'
> +
> +test_expect_success '--prune-merged rejects positional arguments' '
> +	test_must_fail git -C forked branch --prune-merged origin/one other/foreign 2>err &&
> +	test_grep "does not take positional arguments" err
> +'
> +
>   test_done