Re: [PATCH v10 1/5] fetch: add remote.<name>.refmap

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

Hi Harald

On 20/10/2026 14:42, Harald Nordgren via GitGitGadget wrote:
> From: Harald Nordgren <haraldnordgren@gmail.com>
> 
> Add a per-remote config variable, remote.<name>.refmap, that provides
> the default value for --refmap the same way remote.<name>.fetch
> already provides the default refspecs to fetch.

The second half of this sentence seems redundant to me. Can we please 
call the new config setting "remote.<name>.fetchRefmap" so that it is 
clear it applies to fetches. That would also allow us to add a matching 
"remote.<name>.pushRefmap" in the future to map the refnames of refs 
that are pushed without setting up a default set of refs to push.

> Like --refmap itself,
> it only maps refs that are actually being fetched, so it has nothing
> to do when there is nothing explicit to fetch, on the command line or
> via remote.<name>.fetch.

So the default value behaves like the option - why wouldn't it?

> A refspec-less fetch with a refmap configured but nothing else to say
> what to fetch falls back to the same defaults as a remote with no
> refspec or refmap at all. Only an explicit --refmap given on the
> command line with no command-line refspec to go with it is still
> rejected, since that combination is a plain mistake to type, unlike a
> remote.<name>.refmap configured on its own. A remote.<name>.fetch
> that is also configured is used as before.

I'm afraid I cannot understand what this paragraph is trying to say.

> diff --git a/Documentation/config/remote.adoc b/Documentation/config/remote.adoc
>   
> +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].

I'm not sure we need to link to the git fetch documentation twice. It 
would be useful to explain how this interacts with remote.<name>.fetch. 
The documentation for "--refmap" says that if it is given the refspec 
config is ignored - so does setting this mean remote.<name>.fetch is 
ignored?

> diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc
> ++
> +`remote.<name>.refmap` provides the default value for this option, the
> +same way `remote.<name>.fetch` provides the default refspecs to fetch.

As above the second half of this sentence doesn't really add anything.

Thanks

Phillip

>   
>   `-t`::
>   `--tags`::
> diff --git a/builtin/fetch.c b/builtin/fetch.c
> index 1f76ae6242..ffcb5ba29a 100644
> --- a/builtin/fetch.c
> +++ b/builtin/fetch.c
> @@ -518,6 +518,12 @@ static struct ref *get_ref_map(struct remote *remote,
>   	struct ref *rm;
>   	struct ref *ref_map = NULL;
>   	struct ref **tail = &ref_map;
> +	/*
> +	 * The --refmap command line option, if given, takes precedence
> +	 * over remote.<name>.refmap.
> +	 */
> +	struct refspec *effective_refmap =
> +		refmap.nr ? &refmap : remote ? &remote->refmap : NULL;
>   
>   	/* opportunistically-updated references: */
>   	struct ref *orefs = NULL, **oref_tail = &orefs;
> @@ -561,8 +567,8 @@ static struct ref *get_ref_map(struct remote *remote,
>   		 * by ref_remove_duplicates() in favor of one of these
>   		 * opportunistic entries with FETCH_HEAD_IGNORE.
>   		 */
> -		if (refmap.nr)
> -			fetch_refspec = &refmap;
> +		if (effective_refmap && effective_refmap->nr)
> +			fetch_refspec = effective_refmap;
>   		else
>   			fetch_refspec = &remote->fetch;
>   
> diff --git a/remote.c b/remote.c
> index 49ee2ea318..c9252a90f4 100644
> --- a/remote.c
> +++ b/remote.c
> @@ -152,6 +152,7 @@ static struct remote *make_remote(struct remote_state *remote_state,
>   	ret->name = xstrndup(name, len);
>   	refspec_init_push(&ret->push, the_hash_algo);
>   	refspec_init_fetch(&ret->fetch, the_hash_algo);
> +	refspec_init_fetch(&ret->refmap, the_hash_algo);
>   	string_list_init_dup(&ret->server_options);
>   	string_list_init_dup(&ret->negotiation_restrict);
>   	string_list_init_dup(&ret->negotiation_include);
> @@ -176,6 +177,7 @@ static void remote_clear(struct remote *remote)
>   
>   	refspec_clear(&remote->push);
>   	refspec_clear(&remote->fetch);
> +	refspec_clear(&remote->refmap);
>   
>   	free((char *)remote->receivepack);
>   	free((char *)remote->uploadpack);
> @@ -539,6 +541,12 @@ static int handle_config(const char *key, const char *value,
>   			return -1;
>   		refspec_append(&remote->fetch, v);
>   		free(v);
> +	} else if (!strcmp(subkey, "refmap")) {
> +		char *v;
> +		if (git_config_string(&v, key, value))
> +			return -1;
> +		refspec_append(&remote->refmap, v);
> +		free(v);
>   	} else if (!strcmp(subkey, "receivepack")) {
>   		char *v;
>   		if (git_config_string(&v, key, value))
> @@ -995,7 +1003,9 @@ void ref_push_report_free(struct ref_push_report *report)
>   
>   int remote_find_tracking(struct remote *remote, struct refspec_item *refspec)
>   {
> -	return refspec_find_match(&remote->fetch, refspec);
> +	if (remote->fetch.nr)
> +		return refspec_find_match(&remote->fetch, refspec);
> +	return refspec_find_match(&remote->refmap, refspec);
>   }
>   
>   static struct ref *alloc_ref_with_prefix(const char *prefix, size_t prefixlen,
> diff --git a/remote.h b/remote.h
> index cca02033b9..ac485a584d 100644
> --- a/remote.h
> +++ b/remote.h
> @@ -90,6 +90,12 @@ struct remote {
>   
>   	struct refspec fetch;
>   
> +	/*
> +	 * How to map refs fetched without an explicit destination into our
> +	 * own namespace, the same as the --refmap command line option.
> +	 */
> +	struct refspec refmap;
> +
>   	/*
>   	 * The setting for whether to fetch tags (as a separate rule from the
>   	 * configured refspecs);
> diff --git a/t/t5510-fetch.sh b/t/t5510-fetch.sh
> index 17c0be499c..ec5cd9dca6 100755
> --- a/t/t5510-fetch.sh
> +++ b/t/t5510-fetch.sh
> @@ -927,6 +927,69 @@ test_expect_success 'explicit --refmap option overrides remote.*.fetch' '
>   	)
>   '
>   
> +test_expect_success 'remote.*.refmap acts like --refmap on the command line' '
> +	test_when_finished "git -C three config --unset remote.origin.refmap" &&
> +	git branch -f side &&
> +	git -C three config remote.origin.refmap \
> +		"refs/heads/*:refs/remotes/other/*" &&
> +	(
> +		cd three &&
> +		git update-ref refs/remotes/origin/main base-origin-main &&
> +		o=$(git rev-parse --verify refs/remotes/origin/main) &&
> +		git fetch origin main &&
> +		n=$(git rev-parse --verify refs/remotes/origin/main) &&
> +		test "$o" = "$n" &&
> +		test_must_fail git rev-parse --verify refs/remotes/origin/side &&
> +		git rev-parse --verify refs/remotes/other/main
> +	)
> +'
> +
> +check_fetched_refs () {
> +	git for-each-ref --format="%(refname)" refs/remotes/ >actual &&
> +	cat >expect &&
> +	test_cmp expect actual
> +}
> +
> +test_expect_success 'remote.<name>.refmap without tracking (baseline)' '
> +	test_when_finished "rm -fr fetch-refmap-baseline fetch-refmap-upstream" &&
> +	git init -b main fetch-refmap-upstream &&
> +	test_commit -C fetch-refmap-upstream base &&
> +	git -C fetch-refmap-upstream branch other &&
> +	git init fetch-refmap-baseline &&
> +	(
> +		cd fetch-refmap-baseline &&
> +		git remote add origin ../fetch-refmap-upstream &&
> +
> +		# Without fetch refspec, but with fetch refmap.
> +		git config --unset-all remote.origin.fetch &&
> +		git config remote.origin.refmap "+refs/heads/*:refs/remotes/origin/*" &&
> +
> +		# Nothing tracked, nothing fetched, no error.
> +		git fetch origin &&
> +		check_fetched_refs <<-\EOF &&
> +		EOF
> +
> +		# Nothing tracked, explicit ref on the command line.
> +		git fetch origin main &&
> +		check_fetched_refs <<-\EOF &&
> +		refs/remotes/origin/main
> +		EOF
> +
> +		# With both refmap and fetch configured, remote.<name>.fetch
> +		# wins: a refspec-less fetch follows it as usual, and
> +		# remote.<name>.refmap plays no part in deciding what to
> +		# fetch, only in remapping something that is already being
> +		# fetched by name.
> +		git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*" &&
> +		git fetch origin &&
> +		check_fetched_refs <<-\EOF
> +		refs/remotes/origin/HEAD
> +		refs/remotes/origin/main
> +		refs/remotes/origin/other
> +		EOF
> +	)
> +'
> +
>   test_expect_success 'explicitly empty --refmap option disables remote.*.fetch' '
>   	git branch -f side &&
>   	(