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

[PATCH 16/16] doc: promisor: improve acceptFromServer entry

From
Christian Couder <christian.couder@gmail.com>
Date
Mar 23, 2026, 08:05 UTC
Message-ID
<20260323080520.887550-17-christian.couder@gmail.com>
In-Reply-To
<20260323080520.887550-1-christian.couder@gmail.com>

The entry for the `promisor.acceptFromServer` in "Documentation/config/promisor.adoc" has a number of issues:

- it's not clear if new remotes and URLs can be created,
- it looks like a big block of text,
- it's not easy to see all the options,
- it's not easy to see which option is the default one,
- for "knownName", it says "advertised by the client" instead of
  "advertised by the server",
- it doesn't refer to the new related `acceptFromServerUrl`
  option.

Let's address all these issues by rewording large parts of it and using bullet points for the different options.

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
---
 Documentation/config/promisor.adoc | 53 ++++++++++++++++++++----------
 1 file changed, 35 insertions(+), 18 deletions(-)
diff --git a/Documentation/config/promisor.adoc b/Documentation/config/promisor.adoc
index d8e5f4a6dc..1d64e7f1d4 100644
--- a/Documentation/config/promisor.adoc
+++ b/Documentation/config/promisor.adoc
@@ -32,24 +32,41 @@ variable is set to "true", and the "name" and "url" fields are always
 advertised regardless of this setting.
 
 promisor.acceptFromServer::
-	If set to "all", a client will accept all the promisor remotes
-	a server might advertise using the "promisor-remote"
-	capability. If set to "knownName" the client will accept
-	promisor remotes which are already configured on the client
-	and have the same name as those advertised by the client. This
-	is not very secure, but could be used in a corporate setup
-	where servers and clients are trusted to not switch name and
-	URLs. If set to "knownUrl", the client will accept promisor
-	remotes which have both the same name and the same URL
-	configured on the client as the name and URL advertised by the
-	server. This is more secure than "all" or "knownName", so it
-	should be used if possible instead of those options. Default
-	is "none", which means no promisor remote advertised by a
-	server will be accepted. By accepting a promisor remote, the
-	client agrees that the server might omit objects that are
-	lazily fetchable from this promisor remote from its responses
-	to "fetch" and "clone" requests from the client. Name and URL
-	comparisons are case sensitive. See linkgit:gitprotocol-v2[5].
+	Controls which promisor remotes advertised by a server (using the
+	"promisor-remote" protocol capability) a client will accept. By
+	accepting a promisor remote, the client agrees that the server
+	might omit objects that are lazily fetchable from this promisor
+	remote from its responses to "fetch" and "clone" requests.
++
+Note that this option does not cause new remotes to be automatically
+created in the client's configuration. It only allows remotes which
+are somehow already configured to be trusted for the current
+operation, or their fields to be updated (if `promisor.storeFields` is
+set and the remote already exists locally). To allow Git to
+automatically create and persist new remotes from server
+advertisements, use `promisor.acceptFromServerUrl`.
++
+The available options are:
++
+* `none` (default): No promisor remote advertised by a server will be
+  accepted.
++
+* `knownUrl`: The client will accept promisor remotes that are already
+  configured on the client and have both the same name and the same URL
+  as advertised by the server. This is more secure than `all` or
+  `knownName`, and should be used if possible instead of those options.
++
+* `knownName`: The client will accept promisor remotes that are already
+  configured on the client and have the same name as those advertised
+  by the server. This is not very secure, but could be used in a corporate
+  setup where servers and clients are trusted to not switch names and URLs.
++
+* `all`: The client will accept all the promisor remotes a server might
+  advertise. This is the least secure option and should only be used in
+  fully trusted environments.
++
+Name and URL comparisons are case-sensitive. See linkgit:gitprotocol-v2[5]
+for protocol details.
 
 promisor.acceptFromServerUrl::
 	A glob pattern to specify which URLs advertised by a server
-- 
2.53.0.625.g20f70b52bb
Previous: Christian CouderNext: Christian Couder
Message 42 of 47 in “Auto-configure advertised remotes via URL whitelist”
  1. 00/16 Auto-configure advertised remotes via URL whitelistChristian Couder, Mar 23, 2026
  2. 01/16 promisor-remote: try accepted remotes before others in get_direct()Christian Couder, Mar 23, 2026
  3. Patrick SteinhardtMar 26, 2026
  4. Christian CouderApr 2, 2026
  5. 02/16 urlmatch: change 'allow_globs' arg to boolChristian Couder, Mar 23, 2026
  6. 03/16 urlmatch: add url_is_valid_pattern() helperChristian Couder, Mar 23, 2026
  7. Patrick SteinhardtMar 26, 2026
  8. Christian CouderApr 27, 2026
  9. 04/16 promisor-remote: clarify that a remote is ignoredChristian Couder, Mar 23, 2026
  10. Patrick SteinhardtMar 26, 2026
  11. Christian CouderApr 2, 2026
  12. 05/16 promisor-remote: refactor has_control_char()Christian Couder, Mar 23, 2026
  13. 06/16 promisor-remote: refactor accept_from_server()Christian Couder, Mar 23, 2026
  14. 07/16 promisor-remote: keep accepted promisor_info structs aliveChristian Couder, Mar 23, 2026
  15. Patrick SteinhardtMar 26, 2026
  16. 08/16 promisor-remote: remove the 'accepted' strvecChristian Couder, Mar 23, 2026
  17. Patrick SteinhardtMar 26, 2026
  18. Christian CouderApr 2, 2026
  19. 09/16 promisor-remote: add 'local_name' to 'struct promisor_info'Christian Couder, Mar 23, 2026
  20. Patrick SteinhardtMar 26, 2026
  21. Christian CouderApr 27, 2026
  22. 10/16 promisor-remote: pass config entry to all_fields_match() directlyChristian Couder, Mar 23, 2026
  23. Patrick SteinhardtMar 26, 2026
  24. Christian CouderApr 2, 2026
  25. 12/16 t5710: use proper file:// URIs for absolute pathsChristian Couder, Mar 23, 2026
  26. Patrick SteinhardtMar 26, 2026
  27. Christian CouderApr 2, 2026
  28. 13/16 promisor-remote: introduce promisor.acceptFromServerUrlChristian Couder, Mar 23, 2026
  29. Patrick SteinhardtMar 26, 2026
  30. Christian CouderApr 27, 2026
  31. 11/16 promisor-remote: refactor should_accept_remote() control flowChristian Couder, Mar 23, 2026
  32. Patrick SteinhardtMar 26, 2026
  33. Christian CouderApr 2, 2026
  34. 14/16 promisor-remote: trust known remotes matching acceptFromServerUrlChristian Couder, Mar 23, 2026
  35. Junio C HamanoMar 23, 2026
  36. Junio C HamanoMar 23, 2026
  37. Christian CouderMar 27, 2026
  38. Junio C HamanoMar 31, 2026
  39. Christian CouderApr 1, 2026
  40. Patrick SteinhardtMar 26, 2026
  41. Christian CouderApr 27, 2026
  42. 16/16 doc: promisor: improve acceptFromServer entryChristian Couder, Mar 23, 2026
  43. 15/16 promisor-remote: auto-configure unknown remotesChristian Couder, Mar 23, 2026
  44. Patrick SteinhardtMar 26, 2026
  45. Christian CouderApr 27, 2026
  46. Patrick SteinhardtMar 26, 2026
  47. Christian CouderApr 2, 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.