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

[PATCH v3 0/9] Implement `promisor.storeFields` and `--filter=auto`

From
Christian Couder <christian.couder@gmail.com>
Date
Feb 12, 2026, 10:08 UTC
Message-ID
<20260212100843.883623-1-christian.couder@gmail.com>
In-Reply-To
<20260204110818.2919273-1-christian.couder@gmail.com>

Introduction ============

A previous patch series added the possibility to pass additional fields, a "partialCloneFilter" and a "token" for each advertised promisor remote, from a server to a client through the "promisor-remote" capability.

On the client side though, it has so far only been possible to use this new information to compare it with local information and then decide if the corresponding advertised promisor remote is accepted or not.

For the "token" it would be useful if it could be stored on the client. For example in a setup where the client uses specialized remote helpers which need a token to access the promisor remotes advertised by the server, storing the token would allow the token to be used when the client directly accesses a promisor remote for example to lazy fetch some blobs it now needs.

To enable such a workflow, where the server can rotate tokens and the client can have updated tokens from the server by simply fetching from it, the first part of this series introduces a new "promisor.storeFields" configuration option on the client side, similar to the "promisor.checkFields" configuration option. When field names, "token" or "partialCloneFilter", are listed in this new configuration option, then the values of these field names transmitted by the server are stored in the local configuration on the client side.

Note that for security reasons, the corresponding remote name and url of the advertised promisor remotes must have already been configured on the client side. No new remote name nor url are configured.

For the "partialCloneFilter" field, simply storing the value is not enough to enable dynamic updates. Currently, when a user initiates a partial clone with `--filter=<filter-spec>`, that specific <filter-spec> is saved in the client's local configuration (e.g., remote.origin.partialCloneFilter). Subsequent fetches then reuse this value, ignoring suggestions from the server.

To avoid breaking this mechanism and still be able to use the <filter-spec> that the server suggests for the promisor remotes that the client accepts, the second part of this series introduces a new `--filter=auto` mode for `git clone` and `git fetch`.

When `--filter=auto` is used, then "auto" is still saved as the <filter-spec> for the server locally on the client, and then when a fetch-pack happens, instead of passing just "auto", the actual filter requested by the client is computed by combining the <filter-spec>s that the server suggested for the promisor remotes that the client accepted. This uses the "combine" filter mechanism that already exists in "list-objects-filter-options.{c,h}".

This way by just using `--filter=auto` when cloning, a client makes sure it will use the <filter-spec>s suggested by the server for the promisor remotes it accepts.

This work is part of the "LOP" effort documented in:
  Documentation/technical/large-object-promisors.adoc
See that doc for more information on the broader context.

Overview of the patches =======================

Patches 1/9 and 2/9 are the first part of the series and implement the new "promisor.storeFields" configuration option. Patch 1/9 is a small preparatory refactoring.

Patches from 3/9 to 9/9 implement the `--filter=auto` option:
  - Patches 3/9 and 4/9 are cleanups of "builtin/clone.c" and
    "builtin/fetch.c" respectively that make the `filter_options`
    variable local to cmd_clone() or cmd_fetch().
  - Patch 5/9 is a doc update as `--filter=<filter-spec>` wasn't
    documented for `git fetch`.
  - Patch 6/9 improves "list-objects-filter-options.{c,h}" to
    support the new 'auto' mode.
  - Patches 7/9 and 8/9 improves "promisor-remote.{c,h}" to support
    the new 'auto' mode.
  - Patch 9/9 make the new 'auto' mode actually work by wiring up
    everything together.

CI Report =========

All the tests pass, see:
https://github.com/chriscool/git/actions/runs/21940309492

Changes since v2 ================

Thanks to Patrick Steinhardt, Jean-Noël Avila and Junio Hamano for reviewing the previous version!

The patch series has been rebased on top of current 'master' at 864f55e190 (The second batch, 2026-02-09) to avoid a small conflict.

In patch 2/9, new checks have been added to the "clone with promisor.storeFields=partialCloneFilter" test. We now check that a subsequent fetch can update the configuration.

In patch 4/9, a small change has been made to the arguments of `backfill_tags()` in "builtin/fetch.c" to fix a conflict with 'master'.

In patch 5/9, the commit message has been improved.
In patch 7/9, `captured_filters` has been renamed `accepted_filters`.

Patch 8/9 is new. It changes the signature of `promisor_remote_reply()` and allows this function to not assemble a reply string if this is not needed by the caller.

Patch 9/9, has a number of small changes in "fetch-pack.c":
  - The call to `promisor_remote_reply()` is simplified a bit as it
    doesn't require a reply string to be assembled.
  - A comment has been reworded for clarity.
  - The call to `gently_parse_list_objects_filter()` and the check to
    error out in case it fails have been simplified.

Range diff since v2 ===================

 1:  e19b1518cd =  1:  79255ceba7 promisor-remote: refactor initialising field lists
 2:  8f20baac17 !  2:  012aa7ef19 promisor-remote: allow a client to store fields
    @@ t/t5710-promisor-remote-capability.sh: test_expect_success "clone with promisor.
     +	test_must_fail git -C client config remote.otherLop.partialCloneFilter >actual &&
     +
     +	# Check that the largest object is still missing on the server
    -+	check_missing_objects server 1 "$oid"
    ++	check_missing_objects server 1 "$oid" &&
    ++
    ++	# Change the configuration on the server and fetch from the client
    ++	git -C server config remote.lop.partialCloneFilter "blob:limit=7k" &&
    ++	GIT_NO_LAZY_FETCH=0 git -C client fetch \
    ++		--filter="blob:limit=5k" ../server 2>err &&
    ++
    ++	# Check that the fetch updated the configuration on the client
    ++	echo "blob:limit=7k" >expected &&
    ++	git -C client config remote.lop.partialCloneFilter >actual &&
    ++	test_cmp expected actual &&
    ++
    ++	# Check that user is notified when the new filter is stored
    ++	test_grep "Storing new filter from server for remote '\''lop'\''" err &&
    ++	test_grep "'\''blob:limit=8k'\'' -> '\''blob:limit=7k'\''" err
     +'
     +
      test_expect_success "clone with promisor.advertise set to 'true' but don't delete the client" '
 3:  9d53a79600 =  3:  f17a62e73e clone: make filter_options local to cmd_clone()
 4:  b24907e6dc !  4:  3c6e28dd84 fetch: make filter_options local to cmd_fetch()
    @@ builtin/fetch.c: static struct transport *prepare_transport(struct remote *remot
      		set_option(transport, TRANS_OPT_FROM_PROMISOR, "1");
      	}
     @@ builtin/fetch.c: static int backfill_tags(struct display_state *display_state,
    - 			 struct ref_transaction *transaction,
      			 struct ref *ref_map,
      			 struct fetch_head *fetch_head,
    --			 const struct fetch_config *config)
    -+			 const struct fetch_config *config,
    + 			 const struct fetch_config *config,
    +-			 struct ref_update_display_info_array *display_array)
    ++			 struct ref_update_display_info_array *display_array,
     +			 struct list_objects_filter_options *filter_options)
      {
      	int retcode, cannot_reuse;
    @@ builtin/fetch.c: static int do_fetch(struct transport *transport,
      			 * the transaction and don't commit anything.
      			 */
      			if (backfill_tags(&display_state, transport, transaction, tags_ref_map,
    --					  &fetch_head, config))
    -+					  &fetch_head, config, filter_options))
    +-					  &fetch_head, config, &display_array))
    ++					  &fetch_head, config, &display_array, filter_options))
      				retcode = 1;
      		}
      
 5:  90fb77360b !  5:  3037d546b2 doc: fetch: document `--filter=<filter-spec>` option
    @@ Commit message
         The `--filter=<filter-spec>` option is documented in most commands that
         support it except `git fetch`.
     
    -    Let's fix that and document that option using the same words already
    -    used to document it for `git clone`.
    -
    -    Those words could probably be improved, but they are not wrong, so
    -    let's just use them for now and leave improving them for future work.
    +    Let's fix that and document this option. To ensure consistency across
    +    commands, let's reuse the exact description currently found in
    +    `git clone`.
     
         Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
     
 6:  b524b24024 =  6:  9ce57b88dc list-objects-filter-options: support 'auto' mode for --filter
 7:  4ec51ee88f !  7:  37042f7019 promisor-remote: keep advertised filters in memory
    @@ promisor-remote.c: static void filter_promisor_remote(struct repository *repo,
      	struct store_info *store_info = NULL;
      	struct string_list_item *item;
      	bool reload_config = false;
    -+	struct string_list captured_filters = STRING_LIST_INIT_DUP;
    ++	struct string_list accepted_filters = STRING_LIST_INIT_DUP;
      
      	if (!repo_config_get_string_tmp(the_repository, "promisor.acceptfromserver", &accept_str)) {
      		if (!*accept_str || !strcasecmp("None", accept_str))
    @@ promisor-remote.c: static void filter_promisor_remote(struct repository *repo,
     +			/* Capture advertised filters for accepted remotes */
     +			if (advertised->filter) {
     +				struct string_list_item *i;
    -+				i = string_list_append(&captured_filters, advertised->name);
    ++				i = string_list_append(&accepted_filters, advertised->name);
     +				i->util = xstrdup(advertised->filter);
     +			}
      		}
    @@ promisor-remote.c: static void filter_promisor_remote(struct repository *repo,
      	if (reload_config)
      		repo_promisor_remote_reinit(repo);
     +
    -+	/* Apply captured filters to the stable repo state */
    -+	for_each_string_list_item(item, &captured_filters) {
    ++	/* Apply accepted remote filters to the stable repo state */
    ++	for_each_string_list_item(item, &accepted_filters) {
     +		struct promisor_remote *r = repo_promisor_remote_find(repo, item->string);
     +		if (r) {
     +			free(r->advertised_filter);
    @@ promisor-remote.c: static void filter_promisor_remote(struct repository *repo,
     +		}
     +	}
     +
    -+	string_list_clear(&captured_filters, 1);
    ++	string_list_clear(&accepted_filters, 1);
     +
     +	/* Mark the remotes as accepted in the repository state */
     +	for (size_t i = 0; i < accepted->nr; i++) {
 -:  ---------- >  8:  dd17069aad promisor-remote: change promisor_remote_reply()'s signature
 8:  994ecb3317 !  9:  0f9675f477 fetch-pack: wire up and enable auto filter logic
    @@ fetch-pack.c: static struct ref *do_fetch_pack_v2(struct fetch_pack_args *args,
      	struct strvec index_pack_args = STRVEC_INIT;
     +	const char *promisor_remote_config;
     +
    -+	if (server_feature_v2("promisor-remote", &promisor_remote_config)) {
    -+		char *remote_name = promisor_remote_reply(promisor_remote_config);
    -+		free(remote_name);
    -+	}
    ++	if (server_feature_v2("promisor-remote", &promisor_remote_config))
    ++		promisor_remote_reply(promisor_remote_config, NULL);
     +
     +	if (args->filter_options.choice == LOFC_AUTO) {
     +		struct strbuf errbuf = STRBUF_INIT;
     +		char *constructed_filter = promisor_remote_construct_filter(r);
     +
     +		list_objects_filter_release(&args->filter_options);
    -+		/* The result of resolving an 'auto' filter must not be 'auto' */
    ++		/* Disallow 'auto' as a result of the resolution of this 'auto' filter below */
     +		args->filter_options.allow_auto_filter = 0;
     +
    -+		if (constructed_filter)
    -+			gently_parse_list_objects_filter(&args->filter_options,
    -+							 constructed_filter,
    -+							 &errbuf);
    -+
    -+		if (errbuf.len > 0)
    ++		if (constructed_filter &&
    ++		    gently_parse_list_objects_filter(&args->filter_options,
    ++						     constructed_filter,
    ++						     &errbuf))
     +			die(_("couldn't resolve 'auto' filter '%s': %s"),
     +			    constructed_filter, errbuf.buf);
     +
    @@ fetch-pack.c: static struct ref *do_fetch_pack_v2(struct fetch_pack_args *args,
     
      ## t/t5710-promisor-remote-capability.sh ##
     @@ t/t5710-promisor-remote-capability.sh: test_expect_success "clone with promisor.storeFields=partialCloneFilter" '
    - 	check_missing_objects server 1 "$oid"
    + 	test_grep "'\''blob:limit=8k'\'' -> '\''blob:limit=7k'\''" err
      '
      
     +test_expect_success "clone and fetch with --filter=auto" '
Christian Couder (9):
  promisor-remote: refactor initialising field lists
  promisor-remote: allow a client to store fields
  clone: make filter_options local to cmd_clone()
  fetch: make filter_options local to cmd_fetch()
  doc: fetch: document `--filter=<filter-spec>` option
  list-objects-filter-options: support 'auto' mode for --filter
  promisor-remote: keep advertised filters in memory
  promisor-remote: change promisor_remote_reply()'s signature
  fetch-pack: wire up and enable auto filter logic
 Documentation/config/promisor.adoc           |  33 +++
 Documentation/fetch-options.adoc             |  19 ++
 Documentation/git-clone.adoc                 |  25 +-
 Documentation/gitprotocol-v2.adoc            |  24 +-
 Makefile                                     |   1 +
 builtin/clone.c                              |  18 +-
 builtin/fetch.c                              |  50 ++--
 connect.c                                    |   3 +-
 fetch-pack.c                                 |  24 ++
 list-objects-filter-options.c                |  37 ++-
 list-objects-filter-options.h                |   6 +
 list-objects-filter.c                        |   8 +
 promisor-remote.c                            | 256 +++++++++++++++++--
 promisor-remote.h                            |  17 +-
 t/meson.build                                |   1 +
 t/t5710-promisor-remote-capability.sh        | 123 +++++++++
 t/unit-tests/u-list-objects-filter-options.c |  53 ++++
 transport.c                                  |   1 +
 18 files changed, 626 insertions(+), 73 deletions(-)
 create mode 100644 t/unit-tests/u-list-objects-filter-options.c
-- 
2.53.0.70.g3d1fd9d397.dirty
Previous: Christian CouderNext: Christian Couder
Message 42 of 111 in “Implement `promisor.storeFields` and `--filter=auto`”
  1. 0/9 Implement `promisor.storeFields` and `--filter=auto`Christian Couder, Dec 23, 2025
  2. 1/9 promisor-remote: refactor initialising field listsChristian Couder, Dec 23, 2025
  3. 2/9 promisor-remote: allow a client to store fieldsChristian Couder, Dec 23, 2025
  4. Patrick SteinhardtJan 7, 2026
  5. Christian CouderFeb 4, 2026
  6. 3/9 clone: make filter_options local to cmd_clone()Christian Couder, Dec 23, 2025
  7. 4/9 fetch: make filter_options local to cmd_fetch()Christian Couder, Dec 23, 2025
  8. Patrick SteinhardtJan 7, 2026
  9. 5/9 doc: fetch: document `--filter=<filter-spec>` optionChristian Couder, Dec 23, 2025
  10. Jean-Noël AVILADec 26, 2025
  11. Christian CouderFeb 4, 2026
  12. 6/9 list-objects-filter-options: support 'auto' mode for --filterChristian Couder, Dec 23, 2025
  13. Patrick SteinhardtJan 7, 2026
  14. Christian CouderFeb 4, 2026
  15. 7/9 list-objects-filter-options: implement auto filter resolutionChristian Couder, Dec 23, 2025
  16. Patrick SteinhardtJan 7, 2026
  17. Christian CouderFeb 4, 2026
  18. Patrick SteinhardtFeb 11, 2026
  19. Christian CouderFeb 12, 2026
  20. 8/9 promisor-remote: keep advertised filter in memoryChristian Couder, Dec 23, 2025
  21. Patrick SteinhardtJan 7, 2026
  22. Christian CouderFeb 4, 2026
  23. Patrick SteinhardtFeb 11, 2026
  24. Junio C HamanoFeb 11, 2026
  25. Christian CouderFeb 12, 2026
  26. 9/9 fetch-pack: wire up and enable auto filter logicChristian Couder, Dec 23, 2025
  27. Patrick SteinhardtJan 7, 2026
  28. Christian CouderFeb 4, 2026
  29. 0/8 Implement `promisor.storeFields` and `--filter=auto`Christian Couder, Feb 4, 2026
  30. 1/8 promisor-remote: refactor initialising field listsChristian Couder, Feb 4, 2026
  31. 2/8 promisor-remote: allow a client to store fieldsChristian Couder, Feb 4, 2026
  32. 3/8 clone: make filter_options local to cmd_clone()Christian Couder, Feb 4, 2026
  33. 4/8 fetch: make filter_options local to cmd_fetch()Christian Couder, Feb 4, 2026
  34. 5/8 doc: fetch: document `--filter=<filter-spec>` optionChristian Couder, Feb 4, 2026
  35. Patrick SteinhardtFeb 11, 2026
  36. Christian CouderFeb 12, 2026
  37. 6/8 list-objects-filter-options: support 'auto' mode for --filterChristian Couder, Feb 4, 2026
  38. 7/8 promisor-remote: keep advertised filters in memoryChristian Couder, Feb 4, 2026
  39. 8/8 fetch-pack: wire up and enable auto filter logicChristian Couder, Feb 4, 2026
  40. Patrick SteinhardtFeb 11, 2026
  41. Christian CouderFeb 12, 2026
  42. 0/9 Implement `promisor.storeFields` and `--filter=auto`Christian Couder, Feb 12, 2026
  43. 1/9 promisor-remote: refactor initialising field listsChristian Couder, Feb 12, 2026
  44. 2/9 promisor-remote: allow a client to store fieldsChristian Couder, Feb 12, 2026
  45. 3/9 clone: make filter_options local to cmd_clone()Christian Couder, Feb 12, 2026
  46. 4/9 fetch: make filter_options local to cmd_fetch()Christian Couder, Feb 12, 2026
  47. 5/9 doc: fetch: document `--filter=<filter-spec>` optionChristian Couder, Feb 12, 2026
  48. 6/9 list-objects-filter-options: support 'auto' mode for --filterChristian Couder, Feb 12, 2026
  49. Jeff KingFeb 14, 2026
  50. Christian CouderFeb 16, 2026
  51. 7/9 promisor-remote: keep advertised filters in memoryChristian Couder, Feb 12, 2026
  52. 8/9 promisor-remote: change promisor_remote_reply()'s signatureChristian Couder, Feb 12, 2026
  53. Patrick SteinhardtFeb 13, 2026
  54. 9/9 fetch-pack: wire up and enable auto filter logicChristian Couder, Feb 12, 2026
  55. Patrick SteinhardtFeb 13, 2026
  56. Patrick SteinhardtFeb 13, 2026
  57. 0/9 Implement `promisor.storeFields` and `--filter=auto`Christian Couder, Feb 16, 2026
  58. 1/9 promisor-remote: refactor initialising field listsChristian Couder, Feb 16, 2026
  59. 2/9 promisor-remote: allow a client to store fieldsChristian Couder, Feb 16, 2026
  60. 3/9 clone: make filter_options local to cmd_clone()Christian Couder, Feb 16, 2026
  61. 4/9 fetch: make filter_options local to cmd_fetch()Christian Couder, Feb 16, 2026
  62. 5/9 doc: fetch: document `--filter=<filter-spec>` optionChristian Couder, Feb 16, 2026
  63. 6/9 list-objects-filter-options: support 'auto' mode for --filterChristian Couder, Feb 16, 2026
  64. 7/9 promisor-remote: keep advertised filters in memoryChristian Couder, Feb 16, 2026
  65. 8/9 promisor-remote: change promisor_remote_reply()'s signatureChristian Couder, Feb 16, 2026
  66. 9/9 fetch-pack: wire up and enable auto filter logicChristian Couder, Feb 16, 2026
  67. 0/8 Auto-configure advertised remotes via URL allowlistChristian Couder, Apr 27, 2026
  68. 1/8 t5710: simplify 'mkdir X' followed by 'git -C X init'Christian Couder, Apr 27, 2026
  69. 2/8 urlmatch: change 'allow_globs' arg to boolChristian Couder, Apr 27, 2026
  70. 3/8 urlmatch: add url_normalize_pattern() helperChristian Couder, Apr 27, 2026
  71. 4/8 promisor-remote: add 'local_name' to 'struct promisor_info'Christian Couder, Apr 27, 2026
  72. Toon ClaesMay 4, 2026
  73. 5/8 promisor-remote: introduce promisor.acceptFromServerUrlChristian Couder, Apr 27, 2026
  74. 6/8 promisor-remote: trust known remotes matching acceptFromServerUrlChristian Couder, Apr 27, 2026
  75. Toon ClaesMay 8, 2026
  76. Christian CouderMay 19, 2026
  77. Toon ClaesMay 11, 2026
  78. Christian CouderMay 19, 2026
  79. 7/8 promisor-remote: auto-configure unknown remotesChristian Couder, Apr 27, 2026
  80. Toon ClaesMay 11, 2026
  81. Christian CouderMay 19, 2026
  82. 8/8 doc: promisor: improve acceptFromServer entryChristian Couder, Apr 27, 2026
  83. Christian CouderApr 27, 2026
  84. 0/8 Auto-configure advertised remotes via URL allowlistChristian Couder, May 19, 2026
  85. 1/8 t5710: simplify 'mkdir X' followed by 'git -C X init'Christian Couder, May 19, 2026
  86. 2/8 urlmatch: change 'allow_globs' arg to boolChristian Couder, May 19, 2026
  87. 3/8 urlmatch: add url_normalize_pattern() helperChristian Couder, May 19, 2026
  88. 4/8 promisor-remote: add 'local_name' to 'struct promisor_info'Christian Couder, May 19, 2026
  89. Junio C HamanoMay 20, 2026
  90. Christian CouderMay 27, 2026
  91. 5/8 promisor-remote: introduce promisor.acceptFromServerUrlChristian Couder, May 19, 2026
  92. 6/8 promisor-remote: trust known remotes matching acceptFromServerUrlChristian Couder, May 19, 2026
  93. Kristoffer HaugsbakkMay 23, 2026
  94. Christian CouderMay 27, 2026
  95. 7/8 promisor-remote: auto-configure unknown remotesChristian Couder, May 19, 2026
  96. 8/8 doc: promisor: improve acceptFromServer entryChristian Couder, May 19, 2026
  97. 0/8 Auto-configure advertised remotes via URL allowlistChristian Couder, May 27, 2026
  98. 1/8 t5710: simplify 'mkdir X' followed by 'git -C X init'Christian Couder, May 27, 2026
  99. 2/8 urlmatch: change 'allow_globs' arg to boolChristian Couder, May 27, 2026
  100. 3/8 urlmatch: add url_normalize_pattern() helperChristian Couder, May 27, 2026
  101. 4/8 promisor-remote: add 'local_name' to 'struct promisor_info'Christian Couder, May 27, 2026
  102. 5/8 promisor-remote: introduce promisor.acceptFromServerUrlChristian Couder, May 27, 2026
  103. 6/8 promisor-remote: trust known remotes matching acceptFromServerUrlChristian Couder, May 27, 2026
  104. 7/8 promisor-remote: auto-configure unknown remotesChristian Couder, May 27, 2026
  105. 8/8 doc: promisor: improve acceptFromServer entryChristian Couder, May 27, 2026
  106. Kristoffer HaugsbakkJul 4, 2026
  107. Toon ClaesJun 9, 2026
  108. Christian CouderJun 9, 2026
  109. Toon ClaesJun 9, 2026
  110. Junio C HamanoJun 10, 2026
  111. Christian CouderJun 11, 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.