git-mirror/Documentation/config/promisor.adoc

promisor.quiet::
	If set to "true" assume `--quiet` when fetching additional
	objects for a partial clone.

promisor.advertise::
	If set to "true", a server will use the "promisor-remote"
	capability, see linkgit:gitprotocol-v2[5], to advertise the
	promisor remotes it is using, if it uses some. Default is
	"false", which means the "promisor-remote" capability is not
	advertised.

promisor.sendFields::
	A comma or space separated list of additional remote related
	field names. A server sends these field names and the
	associated field values from its configuration when
	advertising its promisor remotes using the "promisor-remote"
	capability, see linkgit:gitprotocol-v2[5]. Currently, only the
	"partialCloneFilter" and "token" field names are supported.
+
`partialCloneFilter`:: contains the partial clone filter
used for the remote.
+
`token`:: contains an authentication token for the remote.
+
When a field name is part of this list and a corresponding
"remote.foo.<field-name>" config variable is set on the server to a
non-empty value, then the field name and value are sent when
advertising the promisor remote "foo".
+
This list has no effect unless the "promisor.advertise" config
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].

promisor.checkFields::
	A comma or space separated list of additional remote related
	field names. A client checks if the values of these fields
	transmitted by a server correspond to the values of these
	fields in its own configuration before accepting a promisor
	remote. Currently, "partialCloneFilter" and "token" are the
	only supported field names.
+
If one of these field names (e.g., "token") is being checked for an
advertised promisor remote (e.g., "foo"), three conditions must be met
for the check of this specific field to pass:
+
--
1. The corresponding local configuration (e.g., `remote.foo.token`)
   must be set.
2. The server must advertise the "token" field for remote "foo".
3. The value of the locally configured `remote.foo.token` must exactly
   match the value advertised by the server for the "token" field.
--
+
If any of these conditions is not met for any field name listed in
`promisor.checkFields`, the advertised remote "foo" is rejected.
+
For the "partialCloneFilter" field, this allows the client to ensure
that the server's filter matches what it expects locally, preventing
inconsistencies in filtering behavior. For the "token" field, this can
be used to verify that authentication credentials match expected
values.
+
Field values are compared case-sensitively.
+
The "name" and "url" fields are always checked according to the
`promisor.acceptFromServer` policy, independently of this setting.
+
The field names and values should be passed by the server through the
"promisor-remote" capability by using the `promisor.sendFields` config
variable. The fields are checked only if the
`promisor.acceptFromServer` config variable is not set to "None". If
set to "None", this config variable has no effect. See
linkgit:gitprotocol-v2[5].

promisor.storeFields::
	A comma or space separated list of additional remote related
	field names. If a client accepts an advertised remote, the
	client will store the values associated with these field names
	taken from the remote advertisement into its configuration,
	and then reload its remote configuration. Currently,
	"partialCloneFilter" and "token" are the only supported field
	names.
+
For example if a server advertises "partialCloneFilter=blob:limit=20k"
for remote "foo", and that remote is accepted, then "blob:limit=20k"
will be stored for the "remote.foo.partialCloneFilter" configuration
variable.
+
If the new field value from an advertised remote is the same as the
existing field value for that remote on the client side, then no
change is made to the client configuration though.
+
When a new value is stored, a message is printed to standard error to
let users know about this.
+
Note that for security reasons, if the remote is not already
configured on the client side, nothing will be stored for that
remote. In any case, no new remote will be created and no URL will be
stored.
+
Before storing a partial clone filter, it's parsed to check it's
valid. If it's not, a warning is emitted and it's not stored.
+
Before storing a token, a check is performed to ensure it contains no
control character. If the check fails, a warning is emitted and it's
not stored.