branch: add --forked filter for --list mode
Add a --forked option to "git branch" list mode that lists only branches whose configured upstream matches <branch>. The argument can be a ref (e.g. "origin/main", "master"), a remote name like "origin" for the branch its origin/HEAD points at, or a shell glob (e.g. "origin/*"), and may be repeated to widen the filter. It is an ordinary list filter, so it combines with the others: git branch --merged origin/main --forked 'origin/*' lists branches forked from origin that are already merged into origin/main, and --no-merged inverts the question. This is the building block for --delete-merged, which deletes the listed branches once they have landed on their upstream. Signed-off-by: Harald Nordgren <haraldnordgren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Harald Nordgren committed
Jul 30, 2026 at 13:58 UTC
bd1a177d7a688fd77fd3750c67f3b330fa5f44f1
5 files changed
+222
-3
Documentation/git-branch.adoc
+11
-1
@@ -13,6 +13,7 @@ git branch [--color[=<when>] | --no-color] [--show-current]
13
[--column[=<options>] | --no-column] [--sort=<key>]
14
[--merged [<commit>]] [--no-merged [<commit>]]
15
[--contains [<commit>]] [--no-contains [<commit>]]
16
+ [(--forked <branch>)...]
17
[--points-at <object>] [--format=<format>]
18
[(-r|--remotes) | (-a|--all)]
19
[--list] [<pattern>...]
@@ -51,7 +52,8 @@ merged into the named commit (i.e. the branches whose tip commits are
52
reachable from the named commit) will be listed. With `--no-merged` only
53
branches not merged into the named commit will be listed. If the _<commit>_
54
argument is missing it defaults to `HEAD` (i.e. the tip of the current
54
-branch).
55
+branch). With `--forked`, only branches whose configured upstream matches
56
+the given branch or pattern will be listed.
57
58
The command's second form creates a new branch head named _<branch-name>_
59
which points to the current `HEAD`, or _<start-point>_ if given. As a
@@ -311,6 +313,14 @@ superproject's "origin/main", but tracks the submodule's "origin/main".
313
Only list branches whose tips are not reachable from
314
_<commit>_ (`HEAD` if not specified). Implies `--list`.
315
316
+`--forked <branch>`::
317
+ Only list branches whose configured upstream matches
318
+ _<branch>_. The argument can be a ref (e.g. `origin/main`,
319
+ `master`), a remote name like `origin` for the branch its
320
+ `origin/HEAD` points at, or a shell-style glob (e.g.
321
+ `'origin/*'`). The option can be repeated to widen the
322
+ filter. Implies `--list`.
323
+
324
`--points-at <object>`::
325
Only list branches of _<object>_.
326
builtin/branch.c
+16
-2
@@ -30,7 +30,7 @@
30
#include "commit-reach.h"
31
32
static const char * const builtin_branch_usage[] = {
33
- N_("git branch [<options>] [-r | -a] [--merged] [--no-merged]"),
33
+ N_("git branch [<options>] [-r | -a] [--merged] [--no-merged] [(--forked <branch>)...]"),
34
N_("git branch [<options>] [-f] [--recurse-submodules] <branch-name> [<start-point>]"),
35
N_("git branch [<options>] [-l] [<pattern>...]"),
36
N_("git branch [<options>] [-r] (-d | -D) <branch-name>..."),
@@ -674,6 +674,16 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
674
free_worktrees(worktrees);
675
}
676
677
+static int parse_opt_forked(const struct option *opt, const char *arg, int unset)
678
+{
679
+ struct ref_filter *filter = opt->value;
680
+
681
+ BUG_ON_OPT_NEG(unset);
682
+ if (ref_filter_forked_add(filter, arg) < 0)
683
+ die(_("'%s' is not a valid branch or pattern"), arg);
684
+ return 0;
685
+}
686
+
687
static GIT_PATH_FUNC(edit_description, "EDIT_DESCRIPTION")
688
689
static int edit_branch_description(const char *branch_name)
@@ -794,6 +804,9 @@ int cmd_branch(int argc,
804
OPT__FORCE(&force, N_("force creation, move/rename, deletion"), PARSE_OPT_NOCOMPLETE),
805
OPT_MERGED(&filter, N_("print only branches that are merged")),
806
OPT_NO_MERGED(&filter, N_("print only branches that are not merged")),
807
+ OPT_CALLBACK_F(0, "forked", &filter, N_("branch"),
808
+ N_("print only branches whose upstream matches <branch> (repeatable)"),
809
+ PARSE_OPT_NONEG, parse_opt_forked),
810
OPT_COLUMN(0, "column", &colopts, N_("list branches in columns")),
811
OPT_REF_SORT(&sorting_options),
812
OPT_CALLBACK(0, "points-at", &filter.points_at, N_("object"),
@@ -839,7 +852,8 @@ int cmd_branch(int argc,
852
list = 1;
853
854
if (filter.with_commit || filter.no_commit ||
842
- filter.reachable_from || filter.unreachable_from || filter.points_at.nr)
855
+ filter.reachable_from || filter.unreachable_from ||
856
+ filter.points_at.nr || filter.forked.nr)
857
list = 1;
858
859
noncreate_actions = !!delete + !!rename + !!copy + !!new_upstream +
ref-filter.c
+70
@@ -2744,6 +2744,72 @@ static int filter_exclude_match(struct ref_filter *filter, const char *refname)
2744
return match_pattern(filter->exclude.v, refname, filter->ignore_case);
2745
}
2746
2747
+static const char *short_upstream_name(const char *full_ref)
2748
+{
2749
+ const char *short_name = full_ref;
2750
+
2751
+ if (!skip_prefix(short_name, "refs/heads/", &short_name))
2752
+ skip_prefix(short_name, "refs/remotes/", &short_name);
2753
+ return short_name;
2754
+}
2755
+
2756
+/*
2757
+ * Match the configured upstream of a branch against the registered
2758
+ * --forked patterns. Exact patterns are compared against the full
2759
+ * upstream refname so they are unambiguous; glob patterns are matched
2760
+ * against the abbreviated upstream so that a glob such as origin/...
2761
+ * works as typed.
2762
+ */
2763
+static int filter_forked_match(struct ref_filter *filter, const char *refname)
2764
+{
2765
+ const char *short_name;
2766
+ struct branch *branch;
2767
+ const char *upstream;
2768
+
2769
+ if (!skip_prefix(refname, "refs/heads/", &short_name))
2770
+ return 0;
2771
+ branch = branch_get(short_name);
2772
+ if (!branch)
2773
+ return 0;
2774
+ upstream = branch_get_upstream(branch, NULL);
2775
+ if (!upstream)
2776
+ return 0;
2777
+
2778
+ for (size_t i = 0; i < filter->forked.nr; i++) {
2779
+ const char *pattern = filter->forked.v[i];
2780
+ if (has_glob_specials(pattern)) {
2781
+ if (!wildmatch(pattern, short_upstream_name(upstream),
2782
+ WM_PATHNAME))
2783
+ return 1;
2784
+ } else if (!strcmp(pattern, upstream)) {
2785
+ return 1;
2786
+ }
2787
+ }
2788
+ return 0;
2789
+}
2790
+
2791
+int ref_filter_forked_add(struct ref_filter *filter, const char *arg)
2792
+{
2793
+ struct object_id oid;
2794
+ char *full_ref = NULL;
2795
+
2796
+ if (has_glob_specials(arg)) {
2797
+ strvec_push(&filter->forked, arg);
2798
+ return 0;
2799
+ }
2800
+
2801
+ if (repo_dwim_ref(the_repository, arg, strlen(arg), &oid,
2802
+ &full_ref, 0) == 1 &&
2803
+ (starts_with(full_ref, "refs/heads/") ||
2804
+ starts_with(full_ref, "refs/remotes/"))) {
2805
+ strvec_push(&filter->forked, full_ref);
2806
+ free(full_ref);
2807
+ return 0;
2808
+ }
2809
+ free(full_ref);
2810
+ return -1;
2811
+}
2812
+
2813
/*
2814
* We need to seek to the reference right after a given marker but excluding any
2815
* matching references. So we seek to the lexicographically next reference.
@@ -2979,6 +3045,9 @@ static struct ref_array_item *apply_ref_filter(const struct reference *ref,
3045
if (filter->points_at.nr && !match_points_at(&filter->points_at, ref->oid, ref->name))
3046
return NULL;
3047
3048
+ if (filter->forked.nr && !filter_forked_match(filter, ref->name))
3049
+ return NULL;
3050
+
3051
/*
3052
* A merge filter is applied on refs pointing to commits. Hence
3053
* obtain the commit using the 'oid' available and discard all
@@ -3764,6 +3833,7 @@ void ref_filter_init(struct ref_filter *filter)
3833
void ref_filter_clear(struct ref_filter *filter)
3834
{
3835
strvec_clear(&filter->exclude);
3836
+ strvec_clear(&filter->forked);
3837
oid_array_clear(&filter->points_at);
3838
commit_list_free(filter->with_commit);
3839
commit_list_free(filter->no_commit);
ref-filter.h
+10
@@ -67,6 +67,7 @@ struct ref_filter {
67
const char **name_patterns;
68
const char *start_after;
69
struct strvec exclude;
70
+ struct strvec forked;
71
struct oid_array points_at;
72
struct commit_list *with_commit;
73
struct commit_list *no_commit;
@@ -110,6 +111,7 @@ struct ref_format {
111
#define REF_FILTER_INIT { \
112
.points_at = OID_ARRAY_INIT, \
113
.exclude = STRVEC_INIT, \
114
+ .forked = STRVEC_INIT, \
115
}
116
#define REF_FORMAT_INIT { \
117
.use_color = GIT_COLOR_UNKNOWN, \
@@ -172,6 +174,14 @@ void ref_sorting_release(struct ref_sorting *);
174
struct ref_sorting *ref_sorting_options(struct string_list *);
175
/* Function to parse --merged and --no-merged options */
176
int parse_opt_merge_filter(const struct option *opt, const char *arg, int unset);
177
+/*
178
+ * Register a --forked <branch> pattern on the filter. The argument is
179
+ * either a ref, which is resolved to its full refname, or a shell-style
180
+ * glob. Branches are kept only when their configured upstream matches
181
+ * one of the registered patterns. Returns -1 if the argument is not a
182
+ * valid ref or pattern.
183
+ */
184
+int ref_filter_forked_add(struct ref_filter *filter, const char *arg);
185
/* Get the current HEAD's description */
186
char *get_head_description(void);
187
/* Set up translated strings in the output. */
t/t3200-branch.sh
+115
@@ -1755,4 +1755,119 @@ test_expect_success 'errors if given a bad branch name' '
1755
test_cmp expect actual
1756
'
1757
1758
+test_expect_success '--forked: setup' '
1759
+ test_create_repo forked-upstream &&
1760
+ (
1761
+ cd forked-upstream &&
1762
+ test_commit base &&
1763
+ git branch one base &&
1764
+ git branch two base
1765
+ ) &&
1766
+
1767
+ test_create_repo forked-other &&
1768
+ (
1769
+ cd forked-other &&
1770
+ test_commit other-base &&
1771
+ git branch foreign other-base
1772
+ ) &&
1773
+
1774
+ git clone forked-upstream forked &&
1775
+ (
1776
+ cd forked &&
1777
+ git remote add -f other ../forked-other &&
1778
+ git branch local-base &&
1779
+ git branch --track local-one origin/one &&
1780
+ git branch --track local-two origin/two &&
1781
+ git branch --track local-foreign other/foreign &&
1782
+ git branch --track local-onbase local-base &&
1783
+
1784
+ git checkout local-one &&
1785
+ test_commit --no-tag local-one-work local-one.t &&
1786
+ git checkout local-foreign &&
1787
+ test_commit --no-tag local-foreign-work local-foreign.t
1788
+ )
1789
+'
1790
+
1791
+test_expect_success '--forked <upstream-tracking-branch> filters by upstream' '
1792
+ git -C forked branch --forked origin/one --format="%(refname:short)" >actual &&
1793
+ echo local-one >expect &&
1794
+ test_cmp expect actual
1795
+'
1796
+
1797
+test_expect_success '--forked <glob> filters by wildmatch' '
1798
+ git -C forked branch --forked "origin/*" --format="%(refname:short)" >actual &&
1799
+ cat >expect <<-\EOF &&
1800
+ local-one
1801
+ local-two
1802
+ main
1803
+ EOF
1804
+ test_cmp expect actual
1805
+'
1806
+
1807
+test_expect_success '--forked <local-branch> matches branches with local upstream' '
1808
+ git -C forked branch --forked local-base --format="%(refname:short)" >actual &&
1809
+ echo local-onbase >expect &&
1810
+ test_cmp expect actual
1811
+'
1812
+
1813
+test_expect_success '--forked can be repeated to widen the filter' '
1814
+ git -C forked branch --forked origin/one --forked other/foreign --format="%(refname:short)" >actual &&
1815
+ cat >expect <<-\EOF &&
1816
+ local-foreign
1817
+ local-one
1818
+ EOF
1819
+ test_cmp expect actual
1820
+'
1821
+
1822
+test_expect_success '--forked combines literal and glob arguments' '
1823
+ git -C forked branch --forked local-base --forked "other/*" --format="%(refname:short)" >actual &&
1824
+ cat >expect <<-\EOF &&
1825
+ local-foreign
1826
+ local-onbase
1827
+ EOF
1828
+ test_cmp expect actual
1829
+'
1830
+
1831
+test_expect_success '--forked "*/*" covers every remote-tracking upstream' '
1832
+ git -C forked branch --forked "*/*" --format="%(refname:short)" >actual &&
1833
+ cat >expect <<-\EOF &&
1834
+ local-foreign
1835
+ local-one
1836
+ local-two
1837
+ main
1838
+ EOF
1839
+ test_cmp expect actual
1840
+'
1841
+
1842
+test_expect_success '--forked composes with --no-merged' '
1843
+ git -C forked branch --forked "origin/*" --no-merged origin/one --format="%(refname:short)" >actual &&
1844
+ echo local-one >expect &&
1845
+ test_cmp expect actual
1846
+'
1847
+
1848
+test_expect_success '--forked <remote> uses the branch <remote>/HEAD points at' '
1849
+ git -C forked branch --forked origin --format="%(refname:short)" >actual &&
1850
+ echo main >expect &&
1851
+ test_cmp expect actual
1852
+'
1853
+
1854
+test_expect_success '--forked narrows a <pattern> argument' '
1855
+ git -C forked branch --forked "origin/*" "local-*" --format="%(refname:short)" >actual &&
1856
+ cat >expect <<-\EOF &&
1857
+ local-one
1858
+ local-two
1859
+ EOF
1860
+ test_cmp expect actual
1861
+'
1862
+
1863
+test_expect_success '--forked rejects unknown branch/pattern' '
1864
+ test_must_fail git -C forked branch --forked nope 2>err &&
1865
+ test_grep "not a valid branch or pattern" err
1866
+'
1867
+
1868
+test_expect_success '--forked requires a value' '
1869
+ test_must_fail git -C forked branch --forked 2>err &&
1870
+ test_grep "requires a value" err
1871
+'
1872
+
1873
test_done