revision: introduce --toplevel-branches

In large repositories which are served at central hubs (such as at
hosting forges), there tend to be huge numbers of refs, and even huge
numbers of branches.  These branches are often of forms like

  refs/heads/${username}/${topic}
  refs/heads/${bot}/${unique_name}

Sometimes, the sheer number of branches is itself a scaling challenge.
There are cases where we'd like a cheap approximation of "the union of
the main integration branches" (e.g. "main develop next maint"), and
it's okay to also take other branches along for the ride but it's nice
to limit how many extra refs we include.

Introduce a new pseudo-revision `--toplevel-branches` for this
purpose.  It is similar to the existing `--branches` pseudo-revision
and its `--branches=<pattern>` sibling, but there's been no ergonomic
way to exclude the large maze of branches in sub-hierarchies (`*` as
a pattern matches across `/`).

The next commit will use this to speed up push time reachability checks.

Add tests to `t6018-rev-list-glob.sh`, which already constructs a
fixture with a mix of top-level branches (`main`, `someref`,
`subspace-x`) and sub-directory branches (`other/three`, `subspace/one`,
`subspace/two`), making it a natural home for the new coverage.

Signed-off-by: Elijah Newren <newren@gmail.com>

Author: newren

Documentation/git-rev-parse.adoc

@@ -199,6 +199,10 @@ If a `pattern` is given, only refs matching the given shell glob are
 shown.  If the pattern does not contain a globbing character (`?`,
 `*`, or `[`), it is turned into a prefix match by appending `/*`.
 
+--toplevel-branches::
+	Show every ref directly under `refs/heads/` (that is, a branch
+	whose short name does not contain a `/`).
+
 --glob=<pattern>::
 	Show all refs matching the shell glob pattern `pattern`. If
 	the pattern does not start with `refs/`, this is automatically

Documentation/rev-list-options.adoc

@@ -170,6 +170,12 @@ endif::git-log[]
 	branches to ones matching given shell glob. If _<pattern>_ lacks '?',
 	'{asterisk}', or '[', '/{asterisk}' at the end is implied.
 
+`--toplevel-branches`::
+	Pretend as if every ref directly under `refs/heads/` is listed on
+	the command line as _<commit>_.  This is a subset of `--branches`
+	which excludes branches in deeper hierarchies, i.e. excluding
+	branches whose short name contains a `/`.
+
 `--tags[=<pattern>]`::
 	Pretend as if all the refs in `refs/tags` are listed
 	on the command line as _<commit>_. If _<pattern>_ is given, limit

builtin/rev-parse.c

@@ -70,6 +70,7 @@ static int is_rev_argument(const char *arg)
 		"--dense",
 		"--branches=",
 		"--branches",
+		"--toplevel-branches",
 		"--header",
 		"--ignore-missing",
 		"--max-age=",
@@ -960,6 +961,15 @@ int cmd_rev_parse(int argc,
 				free(term_bad);
 				continue;
 			}
+			if (!strcmp(arg, "--toplevel-branches")) {
+				if (ref_excludes.hidden_refs_configured)
+					return error(_("options '%s' and '%s' cannot be used together"),
+						     "--exclude-hidden", "--toplevel-branches");
+				refs_for_each_toplevel_branch_ref(get_main_ref_store(the_repository),
+								  show_reference, NULL);
+				clear_ref_exclusions(&ref_excludes);
+				continue;
+			}
 			if (opt_with_value(arg, "--branches", &arg)) {
 				if (ref_excludes.hidden_refs_configured)
 					return error(_("options '%s' and '%s' cannot be used together"),

refs.c

@@ -552,6 +552,41 @@ int refs_for_each_branch_ref(struct ref_store *refs, refs_for_each_cb cb, void *
 	return refs_for_each_ref_ext(refs, cb, cb_data, &opts);
 }
 
+struct toplevel_branch_filter {
+	refs_for_each_cb *fn;
+	void *cb_data;
+};
+
+static int filter_toplevel_branch(const struct reference *ref, void *data)
+{
+	struct toplevel_branch_filter *filter = data;
+
+	/*
+	 * ref->name has had the "refs/heads/" prefix trimmed, so a
+	 * top-level branch like refs/heads/main appears as "main",
+	 * while a sub-directory branch like refs/heads/dscho/wip
+	 * appears as "dscho/wip".
+	 */
+	if (strchr(ref->name, '/'))
+		return 0;
+	return filter->fn(ref, filter->cb_data);
+}
+
+int refs_for_each_toplevel_branch_ref(struct ref_store *refs,
+				      refs_for_each_cb cb, void *cb_data)
+{
+	struct toplevel_branch_filter filter = {
+		.fn = cb,
+		.cb_data = cb_data,
+	};
+	struct refs_for_each_ref_options opts = {
+		.prefix = "refs/heads/",
+		.trim_prefix = strlen("refs/heads/"),
+	};
+	return refs_for_each_ref_ext(refs, filter_toplevel_branch, &filter,
+				     &opts);
+}
+
 int refs_for_each_remote_ref(struct ref_store *refs, refs_for_each_cb cb, void *cb_data)
 {
 	struct refs_for_each_ref_options opts = {

refs.h

@@ -506,6 +506,8 @@ int refs_for_each_tag_ref(struct ref_store *refs,
 			  refs_for_each_cb fn, void *cb_data);
 int refs_for_each_branch_ref(struct ref_store *refs,
 			     refs_for_each_cb fn, void *cb_data);
+int refs_for_each_toplevel_branch_ref(struct ref_store *refs,
+				      refs_for_each_cb fn, void *cb_data);
 int refs_for_each_remote_ref(struct ref_store *refs,
 			     refs_for_each_cb fn, void *cb_data);
 int refs_for_each_replace_ref(struct ref_store *refs,

revision.c

@@ -2328,6 +2328,7 @@ static int handle_revision_opt(struct rev_info *revs, int argc, const char **arg
 
 	/* pseudo revision arguments */
 	if (!strcmp(arg, "--all") || !strcmp(arg, "--branches") ||
+	    !strcmp(arg, "--toplevel-branches") ||
 	    !strcmp(arg, "--tags") || !strcmp(arg, "--remotes") ||
 	    !strcmp(arg, "--reflog") || !strcmp(arg, "--not") ||
 	    !strcmp(arg, "--no-walk") || !strcmp(arg, "--do-walk") ||
@@ -2807,6 +2808,12 @@ static int handle_revision_pseudo_opt(struct rev_info *revs,
 				     "--exclude-hidden", "--branches");
 		handle_refs(refs, revs, *flags, refs_for_each_branch_ref);
 		clear_ref_exclusions(&revs->ref_excludes);
+	} else if (!strcmp(arg, "--toplevel-branches")) {
+		if (revs->ref_excludes.hidden_refs_configured)
+			return error(_("options '%s' and '%s' cannot be used together"),
+				     "--exclude-hidden", "--toplevel-branches");
+		handle_refs(refs, revs, *flags, refs_for_each_toplevel_branch_ref);
+		clear_ref_exclusions(&revs->ref_excludes);
 	} else if (!strcmp(arg, "--bisect")) {
 		read_bisect_terms(&term_bad, &term_good);
 		handle_refs(refs, revs, *flags, for_each_bad_bisect_ref);

t/t6018-rev-list-glob.sh

@@ -423,4 +423,43 @@ test_expect_failure 'shortlog --glob is not confused by option-like argument' '
 
 '
 
+test_expect_success 'rev-parse --toplevel-branches matches only top-level branches' '
+
+	git rev-parse main someref subspace-x | sort >expect &&
+	git rev-parse --toplevel-branches | sort >actual &&
+	test_cmp expect actual
+
+'
+
+test_expect_success 'rev-list --toplevel-branches matches only top-level branches' '
+
+	git rev-list --no-walk main someref subspace-x | sort >expect &&
+	git rev-list --no-walk --toplevel-branches | sort >actual &&
+	test_cmp expect actual
+
+'
+
+test_expect_success 'rev-list --not --toplevel-branches excludes top-level reachable' '
+
+	# "main" itself is a top-level branch, so excluding all
+	# top-level branches from the walk starting at main leaves
+	# nothing to enumerate.
+	git rev-list main --not --toplevel-branches >actual &&
+	test_must_be_empty actual
+
+'
+
+for section in fetch receive uploadpack
+do
+	test_expect_success "rev-parse --exclude-hidden=$section fails with --toplevel-branches" '
+		test_must_fail git rev-parse --exclude-hidden=$section --toplevel-branches 2>err &&
+		test_grep "error: options .--exclude-hidden. and .--toplevel-branches. cannot be used together" err
+	'
+
+	test_expect_success "rev-list --exclude-hidden=$section fails with --toplevel-branches" '
+		test_must_fail git rev-list --exclude-hidden=$section --toplevel-branches 2>err &&
+		test_grep "error: options .--exclude-hidden. and .--toplevel-branches. cannot be used together" err
+	'
+done
+
 test_done