Re: [PATCH v12 1/6] branch: add --forked filter for --list mode

[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>
> 
> Add a --forked option to "git branch" list mode that keeps only
> branches whose configured upstream matches <branch>. The argument
> can be a ref (e.g. "origin/main", "master") or a shell-style
> glob (e.g. "origin/*"). The option can be repeated to widen the
> filter.

Do we want to support a remote name as an alias for $remote/HEAD to 
match "git checkout -b $remote"?

> Because it is a filter on list mode, --forked composes with the
> existing list-mode filters, so
> 
>      git branch --merged origin/main --forked 'origin/*'
> 
> lists branches forked from origin that have already been
> integrated into origin/main, and --no-merged inverts the question.

Nice
> This is the building block for --prune-merged, which deletes the
> listed branches once they have landed on their upstream.
> 
> Signed-off-by: Harald Nordgren <haraldnordgren@gmail.com>
> ---
>   Documentation/git-branch.adoc |   7 ++
>   builtin/branch.c              | 147 +++++++++++++++++++++++++++++++++-
>   ref-filter.c                  |  10 +--
>   ref-filter.h                  |   2 +
>   t/t3200-branch.sh             |  92 +++++++++++++++++++++
>   5 files changed, 249 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/git-branch.adoc b/Documentation/git-branch.adoc
> index c0afddc424..8002d7f38c 100644
> --- a/Documentation/git-branch.adoc
> +++ b/Documentation/git-branch.adoc
> @@ -14,6 +14,7 @@ git branch [--color[=<when>] | --no-color] [--show-current]
>   	   [--merged [<commit>]] [--no-merged [<commit>]]
>   	   [--contains [<commit>]] [--no-contains [<commit>]]
>   	   [--points-at <object>] [--format=<format>]
> +	   [(--forked <branch>)...]

Should this come before --format? I think it logically belongs with 
--merged and --contains which also filter the output.

>   	   [(-r|--remotes) | (-a|--all)]
>   	   [--list] [<pattern>...]
>   git branch [--track[=(direct|inherit)] | --no-track] [-f]
> @@ -199,6 +200,12 @@ This option is only applicable in non-verbose mode.
>   	Print the name of the current branch. In detached `HEAD` state,
>   	nothing is printed.
>   
> +`--forked <branch>`::
> +	List only branches whose configured upstream matches
> +	_<branch>_. The argument can be a ref (e.g. `origin/main`,
> +	`master`) or a shell-style glob (e.g. `'origin/*'`). The
> +	option can be repeated to widen the filter.

This is fine but do we want to add a sentence to the DESCRIPTION as well 
where it talks about "--contains" and "--merged"?

>   `-v`::
>   `-vv`::
>   `--verbose`::
> diff --git a/builtin/branch.c b/builtin/branch.c
> index 1572a4f9ef..12711b29cf 100644
> --- a/builtin/branch.c
> +++ b/builtin/branch.c
> @@ -28,9 +28,10 @@
>   #include "help.h"
>   #include "advice.h"
>   #include "commit-reach.h"
> +#include "wildmatch.h"
>   
>   static const char * const builtin_branch_usage[] = {
> -	N_("git branch [<options>] [-r | -a] [--merged] [--no-merged]"),
> +	N_("git branch [<options>] [-r | -a] [--merged] [--no-merged] [(--forked <branch>)...]"),
>   	N_("git branch [<options>] [-f] [--recurse-submodules] <branch-name> [<start-point>]"),
>   	N_("git branch [<options>] [-l] [<pattern>...]"),
>   	N_("git branch [<options>] [-r] (-d | -D) <branch-name>..."),
> @@ -442,8 +443,12 @@ static char *build_format(struct ref_filter *filter, int maxwidth, const char *r
>   	return strbuf_detach(&fmt, NULL);
>   }
>   
> +static void filter_array_by_forked(struct ref_array *array,
> +				   const struct string_list *upstreams);

We try to avoid forward declarations unless they're really needed - can 
we add the new functions up here instead?

>   static void print_ref_list(struct ref_filter *filter, struct ref_sorting *sorting,
> -			   struct ref_format *format, struct string_list *output)
> +			   struct ref_format *format, struct string_list *output,
> +			   const struct string_list *forked_upstreams)
>   {
>   	int i;
>   	struct ref_array array;
> @@ -463,6 +468,9 @@ static void print_ref_list(struct ref_filter *filter, struct ref_sorting *sortin
>   
>   	filter_refs(&array, filter, filter->kind);
>   
> +	if (forked_upstreams->nr)
> +		filter_array_by_forked(&array, forked_upstreams);

This gets a bit messy below where free elements when we filter "array". 
It would be much nicer to do the filtering in apply_ref_filter() so that 
we don't have to allocate those in the first place. I think it would 
make it simpler to implement --prune-merged as collect_forked_set() 
would become a call to filter_refs() and we could support --forked in 
"git for-each-ref".

> +static int parse_one_forked_arg(const char *arg, struct upstream_pattern *out)
> +{
> +	struct object_id oid;
> +	char *full_ref = NULL;
> +
> +	if (has_glob_specials(arg)) {
> +		out->name = xstrdup(arg);
> +		out->is_wildcard = 1;
> +		return 0;
> +	}
> +
> +	if (repo_dwim_ref(the_repository, arg, strlen(arg), &oid,
> +			  &full_ref, 0) == 1 &&
> +	    (starts_with(full_ref, "refs/heads/") ||
> +	     starts_with(full_ref, "refs/remotes/"))) {
> +		out->name = xstrdup(short_upstream_name(full_ref));

I don't think abbreviating the refname here is a good idea as short 
names are inherently ambiguous - in principle you could have a remote 
tracking branch and a local branch with the same short name. It also 
means we end up reconstructing the full name in a later patch, instead 
we should just call short_upstream_name() where we need the abbreviated 
name.

> +static int upstream_matches(const char *short_upstream,
> +			    const struct upstream_pattern *patterns,
> +			    size_t nr)
> +{
> +	size_t i;
> +
> +	for (i = 0; i < nr; i++) {
> +		const struct upstream_pattern *p = &patterns[i];
> +		if (p->is_wildcard) {
> +			if (!wildmatch(p->name, short_upstream, WM_PATHNAME))
> +				return 1;
> +		} else if (!strcmp(p->name, short_upstream)) {
> +			return 1;
> +		}
> +	}

This is quadratic but maybe we can assume the user wont pass "--forked" 
too many times. If this ever becomes a problem we could use an strset 
for the exact matches and then we only need to loop over the wildmatch 
patterns but we probably don't need to worry about that now.

> +static int branch_upstream_matches(const char *full_refname,
> +				   const struct upstream_pattern *patterns,
> +				   size_t nr_patterns)
> +{
> +	const char *short_name;
> +	struct branch *branch;
> +	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);
> +	if (!upstream)
> +		return 0;
> +	return upstream_matches(short_upstream_name(upstream),

This would be simpler if we matched on full names.

> +static void filter_array_by_forked(struct ref_array *array,
> +				   const struct string_list *upstreams)
> +{
> +	struct upstream_pattern *patterns = NULL;
> +	size_t nr_patterns = 0;
> +	int i, kept = 0;
> +
> +	parse_forked_args(upstreams, &patterns, &nr_patterns);
> +
> +	for (i = 0; i < array->nr; i++) {
> +		struct ref_array_item *item = array->items[i];
> +		if (branch_upstream_matches(item->refname,
> +					    patterns, nr_patterns))
> +			array->items[kept++] = item;
> +		else
> +			free_ref_array_item(item);
> +	}
> +	array->nr = kept;

As I said above this would be nicer if it was implemented in 
apply_ref_filter().

> @@ -714,6 +847,7 @@ int cmd_branch(int argc,
>   	/* possible actions */
>   	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;

Personally I'd use a strvec here as we don't need the "util" member of 
the string list but I'm probably biased as I don't really like the 
string list api.

I like the idea of making this just another filter to "--list". The 
basics of the implementation look reasonable - it should be straight 
forward to match on full refs and move the relavent code into filter-refs.c

Thanks

Phillip

>   	const char *new_upstream = NULL;
>   	int noncreate_actions = 0;
>   	/* possible options */
> @@ -767,6 +901,8 @@ int cmd_branch(int argc,
>   		OPT_BOOL(0, "create-reflog", &reflog, N_("create the branch's reflog")),
>   		OPT_BOOL(0, "edit-description", &edit_description,
>   			 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__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")),
> @@ -815,7 +951,8 @@ int cmd_branch(int argc,
>   		list = 1;
>   
>   	if (filter.with_commit || filter.no_commit ||
> -	    filter.reachable_from || filter.unreachable_from || filter.points_at.nr)
> +	    filter.reachable_from || filter.unreachable_from ||
> +	    filter.points_at.nr || forked_upstreams.nr)
>   		list = 1;
>   
>   	noncreate_actions = !!delete + !!rename + !!copy + !!new_upstream +
> @@ -880,7 +1017,8 @@ int cmd_branch(int argc,
>   		ref_sorting_set_sort_flags_all(sorting, REF_SORTING_ICASE, icase);
>   		ref_sorting_set_sort_flags_all(
>   			sorting, REF_SORTING_DETACHED_HEAD_FIRST, 1);
> -		print_ref_list(&filter, sorting, &format, &output);
> +		print_ref_list(&filter, sorting, &format, &output,
> +			       &forked_upstreams);
>   		print_columns(&output, colopts, NULL);
>   		string_list_clear(&output, 0);
>   		ref_sorting_release(sorting);
> @@ -1020,5 +1158,6 @@ int cmd_branch(int argc,
>   
>   out:
>   	string_list_clear(&sorting_options, 0);
> +	string_list_clear(&forked_upstreams, 0);
>   	return ret;
>   }
> diff --git a/ref-filter.c b/ref-filter.c
> index 1da4c0e60d..65e7bc6785 100644
> --- a/ref-filter.c
> +++ b/ref-filter.c
> @@ -3035,7 +3035,7 @@ static int filter_one(const struct reference *ref, void *cb_data)
>   }
>   
>   /*  Free memory allocated for a ref_array_item */
> -static void free_array_item(struct ref_array_item *item)
> +void free_ref_array_item(struct ref_array_item *item)
>   {
>   	free((char *)item->symref);
>   	if (item->value) {
> @@ -3078,7 +3078,7 @@ static int filter_and_format_one(const struct reference *ref, void *cb_data)
>   
>   	strbuf_release(&output);
>   	strbuf_release(&err);
> -	free_array_item(item);
> +	free_ref_array_item(item);
>   
>   	/*
>   	 * Increment the running count of refs that match the filter. If
> @@ -3098,7 +3098,7 @@ void ref_array_clear(struct ref_array *array)
>   	int i;
>   
>   	for (i = 0; i < array->nr; i++)
> -		free_array_item(array->items[i]);
> +		free_ref_array_item(array->items[i]);
>   	FREE_AND_NULL(array->items);
>   	array->nr = array->alloc = 0;
>   
> @@ -3171,7 +3171,7 @@ static void reach_filter(struct ref_array *array,
>   		if (is_merged == include_reached)
>   			array->items[array->nr++] = array->items[i];
>   		else
> -			free_array_item(item);
> +			free_ref_array_item(item);
>   	}
>   
>   	clear_commit_marks_many(old_nr, to_clear, ALL_REV_FLAGS);
> @@ -3667,7 +3667,7 @@ void pretty_print_ref(const char *name, const struct object_id *oid,
>   
>   	strbuf_release(&err);
>   	strbuf_release(&output);
> -	free_array_item(ref_item);
> +	free_ref_array_item(ref_item);
>   }
>   
>   static int parse_sorting_atom(const char *atom)
> diff --git a/ref-filter.h b/ref-filter.h
> index 120221b47f..3883b9dc62 100644
> --- a/ref-filter.h
> +++ b/ref-filter.h
> @@ -155,6 +155,8 @@ void filter_and_format_refs(struct ref_filter *filter, unsigned int type,
>   			    struct ref_format *format);
>   /*  Clear all memory allocated to ref_array */
>   void ref_array_clear(struct ref_array *array);
> +/*  Free a single item from a ref_array */
> +void free_ref_array_item(struct ref_array_item *item);
>   /*  Used to verify if the given format is correct and to parse out the used atoms */
>   int verify_ref_format(struct ref_format *format);
>   /*  Sort the given ref_array as per the ref_sorting provided */
> diff --git a/t/t3200-branch.sh b/t/t3200-branch.sh
> index e7829c2c4b..4e7deddc04 100755
> --- a/t/t3200-branch.sh
> +++ b/t/t3200-branch.sh
> @@ -1717,4 +1717,96 @@ test_expect_success 'errors if given a bad branch name' '
>   	test_cmp expect actual
>   '
>   
> +test_expect_success '--forked: setup' '
> +	test_create_repo forked-upstream &&
> +	test_commit -C forked-upstream base &&
> +	git -C forked-upstream branch one base &&
> +	git -C forked-upstream branch two base &&
> +
> +	test_create_repo forked-other &&
> +	test_commit -C forked-other other-base &&
> +	git -C forked-other branch foreign other-base &&
> +
> +	git clone forked-upstream forked &&
> +	git -C forked remote add other ../forked-other &&
> +	git -C forked fetch other &&
> +	git -C forked branch local-base &&
> +	git -C forked branch --track local-one origin/one &&
> +	git -C forked branch --track local-two origin/two &&
> +	git -C forked branch --track local-foreign other/foreign &&
> +	git -C forked branch detached &&
> +	git -C forked branch --track local-trunk local-base
> +'
> +
> +test_expect_success '--forked <upstream-tracking-branch> filters by upstream' '
> +	git -C forked branch --forked origin/one --format="%(refname:short)" >actual &&
> +	echo local-one >expect &&
> +	test_cmp expect actual
> +'
> +
> +test_expect_success '--forked <glob> filters by wildmatch' '
> +	git -C forked branch --forked "origin/*" --format="%(refname:short)" >actual &&
> +	cat >expect <<-\EOF &&
> +	local-one
> +	local-two
> +	main
> +	EOF
> +	test_cmp expect actual
> +'
> +
> +test_expect_success '--forked <local-branch> matches branches with local upstream' '
> +	git -C forked branch --forked local-base --format="%(refname:short)" >actual &&
> +	echo local-trunk >expect &&
> +	test_cmp expect actual
> +'
> +
> +test_expect_success '--forked can be repeated to widen the filter' '
> +	git -C forked branch --forked origin/one --forked other/foreign --format="%(refname:short)" >actual &&
> +	cat >expect <<-\EOF &&
> +	local-foreign
> +	local-one
> +	EOF
> +	test_cmp expect actual
> +'
> +
> +test_expect_success '--forked combines literal and glob arguments' '
> +	git -C forked branch --forked local-base --forked "other/*" --format="%(refname:short)" >actual &&
> +	cat >expect <<-\EOF &&
> +	local-foreign
> +	local-trunk
> +	EOF
> +	test_cmp expect actual
> +'
> +
> +test_expect_success '--forked "*/*" covers every remote-tracking upstream' '
> +	git -C forked branch --forked "*/*" --format="%(refname:short)" >actual &&
> +	cat >expect <<-\EOF &&
> +	local-foreign
> +	local-one
> +	local-two
> +	main
> +	EOF
> +	test_cmp expect actual
> +'
> +
> +test_expect_success '--forked composes with --no-merged' '
> +	test_when_finished "git -C forked checkout detached" &&
> +	git -C forked checkout local-one &&
> +	test_commit -C forked local-only &&
> +	git -C forked branch --forked "origin/*" --no-merged origin/one \
> +		--format="%(refname:short)" >actual &&
> +	echo local-one >expect &&
> +	test_cmp expect actual
> +'
> +
> +test_expect_success '--forked rejects unknown branch/pattern' '
> +	test_must_fail git -C forked branch --forked nope 2>err &&
> +	test_grep "not a valid branch or pattern" err
> +'
> +
> +test_expect_success '--forked requires a value' '
> +	test_must_fail git -C forked branch --forked 2>err &&
> +	test_grep "requires a value" err
> +'
> +
>   test_done