| 1 | promisor.quiet:: |
| 2 | If set to "true" assume `--quiet` when fetching additional |
| 3 | objects for a partial clone. |
| 4 | |
| 5 | promisor.advertise:: |
| 6 | If set to "true", a server will use the "promisor-remote" |
| 7 | capability, see linkgit:gitprotocol-v2[5], to advertise the |
| 8 | promisor remotes it is using, if it uses some. Default is |
| 9 | "false", which means the "promisor-remote" capability is not |
| 10 | advertised. |
| 11 | |
| 12 | promisor.sendFields:: |
| 13 | A comma or space separated list of additional remote related |
| 14 | field names. A server sends these field names and the |
| 15 | associated field values from its configuration when |
| 16 | advertising its promisor remotes using the "promisor-remote" |
| 17 | capability, see linkgit:gitprotocol-v2[5]. Currently, only the |
| 18 | "partialCloneFilter" and "token" field names are supported. |
| 19 | + |
| 20 | `partialCloneFilter`:: contains the partial clone filter |
| 21 | used for the remote. |
| 22 | + |
| 23 | `token`:: contains an authentication token for the remote. |
| 24 | + |
| 25 | When a field name is part of this list and a corresponding |
| 26 | "remote.foo.<field-name>" config variable is set on the server to a |
| 27 | non-empty value, then the field name and value are sent when |
| 28 | advertising the promisor remote "foo". |
| 29 | + |
| 30 | This list has no effect unless the "promisor.advertise" config |
| 31 | variable is set to "true", and the "name" and "url" fields are always |
| 32 | advertised regardless of this setting. |
| 33 | |
| 34 | promisor.acceptFromServer:: |
| 35 | If set to "all", a client will accept all the promisor remotes |
| 36 | a server might advertise using the "promisor-remote" |
| 37 | capability. If set to "knownName" the client will accept |
| 38 | promisor remotes which are already configured on the client |
| 39 | and have the same name as those advertised by the client. This |
| 40 | is not very secure, but could be used in a corporate setup |
| 41 | where servers and clients are trusted to not switch name and |
| 42 | URLs. If set to "knownUrl", the client will accept promisor |
| 43 | remotes which have both the same name and the same URL |
| 44 | configured on the client as the name and URL advertised by the |
| 45 | server. This is more secure than "all" or "knownName", so it |
| 46 | should be used if possible instead of those options. Default |
| 47 | is "none", which means no promisor remote advertised by a |
| 48 | server will be accepted. By accepting a promisor remote, the |
| 49 | client agrees that the server might omit objects that are |
| 50 | lazily fetchable from this promisor remote from its responses |
| 51 | to "fetch" and "clone" requests from the client. Name and URL |
| 52 | comparisons are case sensitive. See linkgit:gitprotocol-v2[5]. |
| 53 | |
| 54 | promisor.checkFields:: |
| 55 | A comma or space separated list of additional remote related |
| 56 | field names. A client checks if the values of these fields |
| 57 | transmitted by a server correspond to the values of these |
| 58 | fields in its own configuration before accepting a promisor |
| 59 | remote. Currently, "partialCloneFilter" and "token" are the |
| 60 | only supported field names. |
| 61 | + |
| 62 | If one of these field names (e.g., "token") is being checked for an |
| 63 | advertised promisor remote (e.g., "foo"), three conditions must be met |
| 64 | for the check of this specific field to pass: |
| 65 | + |
| 66 | -- |
| 67 | 1. The corresponding local configuration (e.g., `remote.foo.token`) |
| 68 | must be set. |
| 69 | 2. The server must advertise the "token" field for remote "foo". |
| 70 | 3. The value of the locally configured `remote.foo.token` must exactly |
| 71 | match the value advertised by the server for the "token" field. |
| 72 | -- |
| 73 | + |
| 74 | If any of these conditions is not met for any field name listed in |
| 75 | `promisor.checkFields`, the advertised remote "foo" is rejected. |
| 76 | + |
| 77 | For the "partialCloneFilter" field, this allows the client to ensure |
| 78 | that the server's filter matches what it expects locally, preventing |
| 79 | inconsistencies in filtering behavior. For the "token" field, this can |
| 80 | be used to verify that authentication credentials match expected |
| 81 | values. |
| 82 | + |
| 83 | Field values are compared case-sensitively. |
| 84 | + |
| 85 | The "name" and "url" fields are always checked according to the |
| 86 | `promisor.acceptFromServer` policy, independently of this setting. |
| 87 | + |
| 88 | The field names and values should be passed by the server through the |
| 89 | "promisor-remote" capability by using the `promisor.sendFields` config |
| 90 | variable. The fields are checked only if the |
| 91 | `promisor.acceptFromServer` config variable is not set to "None". If |
| 92 | set to "None", this config variable has no effect. See |
| 93 | linkgit:gitprotocol-v2[5]. |
| 94 | |
| 95 | promisor.storeFields:: |
| 96 | A comma or space separated list of additional remote related |
| 97 | field names. If a client accepts an advertised remote, the |
| 98 | client will store the values associated with these field names |
| 99 | taken from the remote advertisement into its configuration, |
| 100 | and then reload its remote configuration. Currently, |
| 101 | "partialCloneFilter" and "token" are the only supported field |
| 102 | names. |
| 103 | + |
| 104 | For example if a server advertises "partialCloneFilter=blob:limit=20k" |
| 105 | for remote "foo", and that remote is accepted, then "blob:limit=20k" |
| 106 | will be stored for the "remote.foo.partialCloneFilter" configuration |
| 107 | variable. |
| 108 | + |
| 109 | If the new field value from an advertised remote is the same as the |
| 110 | existing field value for that remote on the client side, then no |
| 111 | change is made to the client configuration though. |
| 112 | + |
| 113 | When a new value is stored, a message is printed to standard error to |
| 114 | let users know about this. |
| 115 | + |
| 116 | Note that for security reasons, if the remote is not already |
| 117 | configured on the client side, nothing will be stored for that |
| 118 | remote. In any case, no new remote will be created and no URL will be |
| 119 | stored. |
| 120 | + |
| 121 | Before storing a partial clone filter, it's parsed to check it's |
| 122 | valid. If it's not, a warning is emitted and it's not stored. |
| 123 | + |
| 124 | Before storing a token, a check is performed to ensure it contains no |
| 125 | control character. If the check fails, a warning is emitted and it's |
| 126 | not stored. |