git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v8 3/5] fetch: infer branches to fetch from a refmap-only remote

From
Harald Nordgren via GitGitGadget <gitgitgadget@gmail.com>
Date
Oct 10, 2026, 08:02 UTC
Message-ID
<a39316d233ee656c6e003927e9e3e526ada0553e.1791619334.git.gitgitgadget@gmail.com>
In-Reply-To
<pull.2412.v8.git.git.1791619334.gitgitgadget@gmail.com>
From: Harald Nordgren <haraldnordgren@gmail.com>

Configuring remote.<name>.refmap without remote.<name>.fetch used to make a refspec-less "git fetch <name>" fail with "--refmap option is only meaningful with command-line refspec(s)", since a refmap only says where to put fetched refs, not what to fetch.

Make that case infer what to fetch: the local branches whose @{upstream} is already on that remote. This lets a remote be configured to fetch only the branches actually in use, without listing them by hand in remote.<name>.fetch, and without needing to touch the command line every time.

Signed-off-by: Harald Nordgren <haraldnordgren@gmail.com>
---
 Documentation/config/remote.adoc |   5 +-
 Documentation/fetch-options.adoc |   6 +-
 builtin/fetch.c                  |  41 ++++++++++-
 remote.c                         |  24 +++++++
 remote.h                         |   4 ++
 t/meson.build                    |   1 +
 t/t5586-fetch-refmap.sh          | 119 +++++++++++++++++++++++++++++++
 7 files changed, 194 insertions(+), 6 deletions(-)
 create mode 100755 t/t5586-fetch-refmap.sh
diff --git a/Documentation/config/remote.adoc b/Documentation/config/remote.adoc
index 103eada406..7c52e443a5 100644
--- a/Documentation/config/remote.adoc
+++ b/Documentation/config/remote.adoc
@@ -36,7 +36,10 @@ remote.<name>.fetch::
 remote.<name>.refmap::
 	The default value of the `--refmap` option for linkgit:git-fetch[1].
 	Used to map remote refs being fetched to remote-tracking refs to
-	store. See the `--refmap` entry in linkgit:git-fetch[1].
+	store. If `remote.<name>.fetch` is not set either, a refspec-less
+	fetch infers what to fetch from local branches built on this
+	remote, instead of fetching every branch it has. See the
+	`--refmap` entry in linkgit:git-fetch[1].
 
 remote.<name>.push::
 	The default set of "refspec" for linkgit:git-push[1]. See
diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc
index c2101a7b39..90b9e13ac2 100644
--- a/Documentation/fetch-options.adoc
+++ b/Documentation/fetch-options.adoc
@@ -245,8 +245,10 @@ endif::git-pull[]
 	command-line arguments. See section on "Configured Remote-tracking
 	Branches" for details.
 +
-`remote.<name>.refmap` provides the default value for this option, the
-same way `remote.<name>.fetch` provides the default refspecs to fetch.
+When a refmap is active (from `--refmap` or `remote.<name>.refmap`) but
+nothing to fetch is specified on the command line, nor is there a
+`remote.<name>.fetch`, branches from the remote that are used as the
+`@{upstream}` of our local branches are fetched.
 
 `-t`::
 `--tags`::
diff --git a/builtin/fetch.c b/builtin/fetch.c
index 4753656288..de3298c0b1 100644
--- a/builtin/fetch.c
+++ b/builtin/fetch.c
@@ -515,6 +515,8 @@ static struct ref *get_ref_map(struct remote *remote,
 	 */
 	struct refspec *effective_refmap =
 		refmap.nr ? &refmap : remote ? &remote->refmap : NULL;
+	struct refspec inferred_rs;
+	int infer_from_refmap = 0;
 
 	/* opportunistically-updated references: */
 	struct ref *orefs = NULL, **oref_tail = &orefs;
@@ -522,15 +524,32 @@ static struct ref *get_ref_map(struct remote *remote,
 	struct hashmap existing_refs;
 	int existing_refs_populated = 0;
 
+	refspec_init_fetch(&inferred_rs, the_hash_algo);
+
 	filter_prefetch_refspec(rs);
 	if (remote)
 		filter_prefetch_refspec(&remote->fetch);
 
+	if (!rs->nr && remote && !remote->fetch.nr &&
+	    effective_refmap && effective_refmap->nr) {
+		struct string_list tracked = STRING_LIST_INIT_DUP;
+		struct string_list_item *item;
+
+		branches_tracking_remote(the_repository, remote, &tracked);
+		for_each_string_list_item(item, &tracked)
+			refspec_append(&inferred_rs, item->string);
+		string_list_clear(&tracked, 0);
+
+		rs = &inferred_rs;
+		infer_from_refmap = 1;
+	}
+
 	if (rs->nr) {
 		struct refspec *fetch_refspec;
 
 		for (i = 0; i < rs->nr; i++) {
-			get_fetch_map(remote_refs, &rs->items[i], &tail, 0);
+			get_fetch_map(remote_refs, &rs->items[i], &tail,
+				      infer_from_refmap);
 			if (rs->items[i].dst && rs->items[i].dst[0])
 				*autotags = 1;
 		}
@@ -565,6 +584,8 @@ static struct ref *get_ref_map(struct remote *remote,
 
 		for (i = 0; i < fetch_refspec->nr; i++)
 			get_fetch_map(ref_map, &fetch_refspec->items[i], &oref_tail, 1);
+	} else if (infer_from_refmap) {
+		/* Already fully handled above. */
 	} else if (refmap.nr) {
 		die("--refmap option is only meaningful with command-line refspec(s)");
 	} else {
@@ -660,6 +681,7 @@ static struct ref *get_ref_map(struct remote *remote,
 	if (existing_refs_populated)
 		hashmap_clear_and_free(&existing_refs, struct refname_hash_entry, ent);
 
+	refspec_clear(&inferred_rs);
 	return ref_map;
 }
 
@@ -1983,11 +2005,24 @@ static int do_fetch(struct transport *transport,
 				    item->string);
 		string_list_clear(&tracked, 0);
 	} else {
+		/*
+		 * The --refmap command line option, if given, takes
+		 * precedence over remote.<name>.refmap.
+		 */
+		struct refspec *effective_refmap = refmap.nr ? &refmap :
+			&transport->remote->refmap;
 		struct string_list tracked = STRING_LIST_INIT_DUP;
 		struct string_list_item *item;
 
-		collect_upstream_from_remote(the_repository, &tracked,
-					      transport->remote, NULL);
+		if (effective_refmap->nr) {
+			branches_tracking_remote(the_repository,
+						  transport->remote, &tracked);
+			if (follow_remote_head != FOLLOW_REMOTE_NEVER)
+				do_set_head = 1;
+		} else {
+			collect_upstream_from_remote(the_repository, &tracked,
+						      transport->remote, NULL);
+		}
 		for_each_string_list_item(item, &tracked)
 			strvec_push(&transport_ls_refs_options.ref_prefixes,
 				    item->string);
diff --git a/remote.c b/remote.c
index 5e980625b8..703c71ba45 100644
--- a/remote.c
+++ b/remote.c
@@ -1899,6 +1899,30 @@ void collect_upstream_from_remote(struct repository *repo,
 		string_list_insert(tracked, branch->merge[i]->src);
 }
 
+struct branches_tracking_remote_cb_data {
+	struct repository *repo;
+	struct remote *remote;
+	struct string_list *tracked;
+};
+
+static int add_if_tracking_remote(const struct reference *ref, void *cb_data)
+{
+	struct branches_tracking_remote_cb_data *data = cb_data;
+
+	collect_upstream_from_remote(data->repo, data->tracked, data->remote,
+				      ref->name);
+	return 0;
+}
+
+void branches_tracking_remote(struct repository *repo, struct remote *remote,
+			       struct string_list *tracked)
+{
+	struct branches_tracking_remote_cb_data data = { repo, remote, tracked };
+
+	refs_for_each_branch_ref(get_main_ref_store(repo),
+				  add_if_tracking_remote, &data);
+}
+
 __attribute__((format (printf,2,3)))
 static char *error_buf(struct strbuf *err, const char *fmt, ...)
 {
diff --git a/remote.h b/remote.h
index 7c86c529b6..62265346d3 100644
--- a/remote.h
+++ b/remote.h
@@ -368,6 +368,10 @@ void collect_upstream_from_remote(struct repository *repo,
 				   struct remote *remote,
 				   const char *refname);
 
+/* fills tracked with the refname of every local branch's upstream on remote */
+void branches_tracking_remote(struct repository *repo, struct remote *remote,
+			       struct string_list *tracked);
+
 /* list of the remote in a group as configured */
 struct remote_group_data {
 	const char *name;
diff --git a/t/meson.build b/t/meson.build
index f65eb04684..e287a6b947 100644
--- a/t/meson.build
+++ b/t/meson.build
@@ -730,6 +730,7 @@ integration_tests = [
   't5582-fetch-negative-refspec.sh',
   't5583-push-branches.sh',
   't5584-http-429-retry.sh',
+  't5586-fetch-refmap.sh',
   't5600-clone-fail-cleanup.sh',
   't5601-clone.sh',
   't5602-clone-remote-exec.sh',
diff --git a/t/t5586-fetch-refmap.sh b/t/t5586-fetch-refmap.sh
new file mode 100755
index 0000000000..b81fc48cbe
--- /dev/null
+++ b/t/t5586-fetch-refmap.sh
@@ -0,0 +1,119 @@
+#!/bin/sh
+
+test_description='"git fetch" with a remote.<name>.refmap but no remote.<name>.fetch
+
+When a remote has a refmap configured but no fetch refspec, a
+refspec-less fetch infers what to fetch from the local branches whose
+@{upstream} is on that remote.
+'
+
+GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME=main
+export GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME
+
+. ./test-lib.sh
+
+test_expect_success 'setup' '
+	test_commit main-1 &&
+	test_commit main-2 &&
+	git checkout -b side main-1 &&
+	test_commit side-1 &&
+	git checkout -b next main-1 &&
+	test_commit next-1 &&
+	git checkout main
+'
+
+test_expect_success 'clone shallow and single-branch, then add a second remote' '
+	git clone --no-local --depth=1 --branch main --single-branch . client &&
+	(
+		cd client &&
+		git remote add upstream .. &&
+		test_might_fail git config unset remote.upstream.fetch &&
+		git config remote.upstream.refmap \
+			"+refs/heads/*:refs/remotes/upstream/*"
+	)
+'
+
+test_expect_success 'a bare fetch needs nothing until a branch is tracked' '
+	(
+		cd client &&
+		git fetch upstream &&
+		git for-each-ref --format="%(refname)" refs/remotes/upstream >actual &&
+		test_must_be_empty actual
+	)
+'
+
+test_expect_success 'an explicit one-time fetch lets a branch be tracked' '
+	(
+		cd client &&
+		git fetch upstream main &&
+		git branch --set-upstream-to=upstream/main &&
+		test_cmp_config upstream branch.main.remote &&
+		test_cmp_config refs/heads/main branch.main.merge
+	)
+'
+
+test_expect_success 'a branch checked out from a one-time fetch is kept updated by later plain fetches' '
+	(
+		cd client &&
+		git fetch upstream side:refs/remotes/upstream/side &&
+		git branch side-topic upstream/side
+	) &&
+	git checkout side &&
+	test_commit side-2 &&
+	git checkout main &&
+	(
+		cd client &&
+		git fetch upstream &&
+		git for-each-ref --format="%(refname)" refs/remotes/upstream >actual &&
+		cat >expect <<-\EOF &&
+		refs/remotes/upstream/HEAD
+		refs/remotes/upstream/main
+		refs/remotes/upstream/side
+		EOF
+		test_cmp expect actual &&
+		git rev-parse refs/remotes/upstream/side >actual-oid &&
+		git -C .. rev-parse side >expect-oid &&
+		test_cmp expect-oid actual-oid
+	)
+'
+
+test_expect_success 'a second branch tracking the same upstream branch does not fetch it twice' '
+	(
+		cd client &&
+		git branch side-topic-2 upstream/side &&
+		git fetch upstream &&
+		git for-each-ref --format="%(refname)" refs/remotes/upstream >actual &&
+		cat >expect <<-\EOF &&
+		refs/remotes/upstream/HEAD
+		refs/remotes/upstream/main
+		refs/remotes/upstream/side
+		EOF
+		test_cmp expect actual
+	)
+'
+
+test_expect_success 'a branch tracking a different remote is not fetched from upstream' '
+	(
+		cd client &&
+		git remote add other .. &&
+		git fetch other next:refs/remotes/other/next &&
+		git branch next-topic other/next &&
+		git fetch upstream &&
+		git for-each-ref --format="%(refname)" refs/remotes/upstream >actual &&
+		cat >expect <<-\EOF &&
+		refs/remotes/upstream/HEAD
+		refs/remotes/upstream/main
+		refs/remotes/upstream/side
+		EOF
+		test_cmp expect actual
+	)
+'
+
+test_expect_success 'git remote show does not choke on a refmap-only remote' '
+	(
+		cd client &&
+		git remote show upstream
+	)
+'
+
+test_done

-- 
gitgitgadget
Previous: Harald Nordgren via GitGitGadgetNext: Harald Nordgren via GitGitGadget
Message 59 of 61 in “fetch: add config to avoid fetching every branch in shallow repo”
  1. fetch: add config to avoid fetching every branch in shallow repoHarald Nordgren via GitGitGadget, Sep 19, 2026
  2. Phillip WoodSep 21, 2026
  3. Harald NordgrenSep 21, 2026
  4. Harald NordgrenSep 22, 2026
  5. Phillip WoodSep 22, 2026
  6. Harald NordgrenSep 22, 2026
  7. Phillip WoodSep 23, 2026
  8. Junio C HamanoSep 22, 2026
  9. Harald NordgrenSep 22, 2026
  10. Phillip WoodSep 23, 2026
  11. Junio C HamanoSep 23, 2026
  12. D. Ben KnobleSep 23, 2026
  13. Junio C HamanoSep 23, 2026
  14. D. Ben KnobleSep 24, 2026
  15. Junio C HamanoSep 24, 2026
  16. fetch: avoid fetching every branch of a new remote in a shallow repoHarald Nordgren via GitGitGadget, Sep 23, 2026
  17. Junio C HamanoSep 23, 2026
  18. 0/4 fetch: avoid fetching every branch of a new remote in a shallow repoHarald Nordgren via GitGitGadget, Sep 25, 2026
  19. 1/4 fetch: add remote.<name>.refmapHarald Nordgren via GitGitGadget, Sep 25, 2026
  20. Junio C HamanoSep 25, 2026
  21. 2/4 fetch: infer branches to fetch from a refmap-only remoteHarald Nordgren via GitGitGadget, Sep 25, 2026
  22. Junio C HamanoSep 25, 2026
  23. 3/4 remote: add "git remote add --limited-fetch"Harald Nordgren via GitGitGadget, Sep 25, 2026
  24. 4/4 remote: default to --limited-fetch in a shallow repositoryHarald Nordgren via GitGitGadget, Sep 25, 2026
  25. 0/4 fetch: avoid fetching every branch of a new remote in a shallow repoHarald Nordgren via GitGitGadget, Sep 29, 2026
  26. 1/4 fetch: add remote.<name>.refmapHarald Nordgren via GitGitGadget, Sep 29, 2026
  27. 2/4 fetch: infer branches to fetch from a refmap-only remoteHarald Nordgren via GitGitGadget, Sep 29, 2026
  28. Harald NordgrenSep 29, 2026
  29. Junio C HamanoSep 29, 2026
  30. 3/4 remote: add "git remote add --limited-fetch"Harald Nordgren via GitGitGadget, Sep 29, 2026
  31. 4/4 remote: default to --limited-fetch in a shallow repositoryHarald Nordgren via GitGitGadget, Sep 29, 2026
  32. Junio C HamanoSep 29, 2026
  33. 0/4 fetch: avoid fetching every branch of a new remote in a shallow repoHarald Nordgren via GitGitGadget, Oct 2, 2026
  34. 1/4 fetch: add remote.<name>.refmapHarald Nordgren via GitGitGadget, Oct 2, 2026
  35. 2/4 fetch: infer branches to fetch from a refmap-only remoteHarald Nordgren via GitGitGadget, Oct 2, 2026
  36. 3/4 remote: add "git remote add --limited-fetch"Harald Nordgren via GitGitGadget, Oct 2, 2026
  37. Junio C HamanoOct 2, 2026
  38. 4/4 remote: default to --limited-fetch in a shallow repositoryHarald Nordgren via GitGitGadget, Oct 2, 2026
  39. 0/4 fetch: avoid fetching every branch of a new remote in a shallow repoHarald Nordgren via GitGitGadget, Oct 4, 2026
  40. 1/4 fetch: add remote.<name>.refmapHarald Nordgren via GitGitGadget, Oct 4, 2026
  41. 2/4 fetch: infer branches to fetch from a refmap-only remoteHarald Nordgren via GitGitGadget, Oct 4, 2026
  42. 3/4 remote: add "git remote add --limited-fetch"Harald Nordgren via GitGitGadget, Oct 4, 2026
  43. 4/4 remote: default to --limited-fetch in a shallow repositoryHarald Nordgren via GitGitGadget, Oct 4, 2026
  44. Junio C HamanoOct 4, 2026
  45. Harald NordgrenOct 4, 2026
  46. Junio C HamanoOct 5, 2026
  47. Harald NordgrenOct 5, 2026
  48. 0/4 fetch: avoid fetching every branch of a new remote in a shallow repoHarald Nordgren via GitGitGadget, Oct 7, 2026
  49. 1/4 fetch: add remote.<name>.refmapHarald Nordgren via GitGitGadget, Oct 7, 2026
  50. 2/4 fetch: infer branches to fetch from a refmap-only remoteHarald Nordgren via GitGitGadget, Oct 7, 2026
  51. Junio C HamanoOct 8, 2026
  52. Harald NordgrenOct 9, 2026
  53. Harald NordgrenOct 9, 2026
  54. 3/4 remote: add "git remote add --limited-fetch"Harald Nordgren via GitGitGadget, Oct 7, 2026
  55. 4/4 remote: default to --limited-fetch in a shallow repositoryHarald Nordgren via GitGitGadget, Oct 7, 2026
  56. 0/5 fetch: avoid fetching every branch of a new remote in a shallow repoHarald Nordgren via GitGitGadget, Oct 10, 2026
  57. 1/5 fetch: add remote.<name>.refmapHarald Nordgren via GitGitGadget, Oct 10, 2026
  58. 2/5 fetch: extract collect_upstream_from_remote() helperHarald Nordgren via GitGitGadget, Oct 10, 2026
  59. 3/5 fetch: infer branches to fetch from a refmap-only remoteHarald Nordgren via GitGitGadget, Oct 10, 2026
  60. 4/5 remote: add "git remote add --limited-fetch"Harald Nordgren via GitGitGadget, Oct 10, 2026
  61. 5/5 remote: default to --limited-fetch in a shallow repositoryHarald Nordgren via GitGitGadget, Oct 10, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.