| 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 | Controls which promisor remotes advertised by a server (using the |
| 36 | "promisor-remote" protocol capability) a client will accept. By |
| 37 | accepting a promisor remote, the client agrees that the server |
| 38 | might omit objects that are lazily fetchable from this promisor |
| 39 | remote from its responses to "fetch" and "clone" requests. |
| 40 | + |
| 41 | Note that this option does not cause new remotes to be automatically |
| 42 | created in the client's configuration. It only allows remotes which |
| 43 | are somehow already configured to be trusted for the current |
| 44 | operation, or their fields to be updated (if `promisor.storeFields` is |
| 45 | set and the remote already exists locally). To allow Git to |
| 46 | automatically create and persist new remotes from server |
| 47 | advertisements, use `promisor.acceptFromServerUrl`. |
| 48 | + |
| 49 | The available options are: |
| 50 | + |
| 51 | * `none` (default): No promisor remote advertised by a server will be |
| 52 | accepted. |
| 53 | + |
| 54 | * `knownUrl`: The client will accept promisor remotes that are already |
| 55 | configured on the client and have both the same name and the same URL |
| 56 | as advertised by the server. This is more secure than `all` or |
| 57 | `knownName`, and should be used if possible instead of those options. |
| 58 | + |
| 59 | * `knownName`: The client will accept promisor remotes that are already |
| 60 | configured on the client and have the same name as those advertised |
| 61 | by the server. This is not very secure, but could be used in a corporate |
| 62 | setup where servers and clients are trusted to not switch names and URLs. |
| 63 | + |
| 64 | * `all`: The client will accept all the promisor remotes a server might |
| 65 | advertise. This is the least secure option and should only be used in |
| 66 | fully trusted environments. |
| 67 | + |
| 68 | Name and URL comparisons are case-sensitive. See linkgit:gitprotocol-v2[5] |
| 69 | for protocol details. |
| 70 | |
| 71 | promisor.acceptFromServerUrl:: |
| 72 | A glob pattern to specify which server-advertised URLs a |
| 73 | client is allowed to act on. When a URL matches, the client |
| 74 | will accept the advertised remote as a promisor remote, may |
| 75 | automatically create a new remote configuration for it and may |
| 76 | automatically accept field updates (such as authentication |
| 77 | tokens) from the server, even if `promisor.acceptFromServer` |
| 78 | is set to `none` (the default). |
| 79 | + |
| 80 | This option can appear multiple times in config files. An advertised |
| 81 | URL will be accepted if it matches _ANY_ glob pattern specified by |
| 82 | this option in _ANY_ config file read by Git. |
| 83 | + |
| 84 | When both `promisor.acceptFromServer` and `promisor.acceptFromServerUrl` |
| 85 | are set, `promisor.acceptFromServerUrl` is consulted first and takes |
| 86 | precedence: if a matching pattern leads to acceptance (either by |
| 87 | auto-configuring an unknown remote or by accepting field updates for |
| 88 | a known remote whose URL matches both the local configuration and the |
| 89 | allowlist), the advertised remote is accepted regardless of the |
| 90 | `promisor.acceptFromServer` setting. If no pattern in |
| 91 | `promisor.acceptFromServerUrl` triggers acceptance, the decision is |
| 92 | left to `promisor.acceptFromServer`. |
| 93 | + |
| 94 | Note however that, even when an advertised URL matches a pattern in |
| 95 | `promisor.acceptFromServerUrl`, an already-existing remote on the |
| 96 | client whose name matches the advertised name but whose configured URL |
| 97 | differs from the advertised one will _NOT_ be accepted through |
| 98 | `promisor.acceptFromServerUrl`. This prevents a server from silently |
| 99 | re-pointing an existing client-side remote at a different URL. (Such a |
| 100 | remote may still be accepted through `promisor.acceptFromServer=all` |
| 101 | or `=knownName`, which have their own, looser semantics; see the |
| 102 | documentation of that option.) |
| 103 | + |
| 104 | Be _VERY_ careful with these patterns: `*` matches any sequence of |
| 105 | characters within the 'host' and 'path' parts of a URL (but cannot |
| 106 | cross part boundaries). An overly broad pattern is a major security |
| 107 | risk, as a matching URL allows a server to auto-configure new remotes |
| 108 | and to update fields (such as authentication tokens) on known remotes |
| 109 | without further confirmation. To minimize security risks, follow these |
| 110 | guidelines: |
| 111 | + |
| 112 | -- |
| 113 | 1. Start with a secure protocol scheme, like `https://` or `ssh://`. |
| 114 | + |
| 115 | 2. Only allow domain names or paths where you control and trust _ALL_ |
| 116 | the content. Be especially careful with shared hosting platforms |
| 117 | like `github.com` or `gitlab.com`. A broad pattern like |
| 118 | `https://gitlab.com/*` is dangerous because it trusts every |
| 119 | repository on the entire platform. Always restrict such patterns to |
| 120 | your specific organization or namespace (e.g., |
| 121 | `https://gitlab.com/your-org/*`). |
| 122 | + |
| 123 | 3. Never use globs at the end of domain names. For example, |
| 124 | `https://cdn.your-org.com/*` might be safe, but |
| 125 | `https://cdn.your-org.com*/*` is a major security risk because |
| 126 | the latter matches `https://cdn.your-org.com.hacker.net/repo`. |
| 127 | + |
| 128 | 4. Be careful using globs at the beginning of domain names. While the |
| 129 | code ensures a `*` in the host cannot cross into the path, a |
| 130 | pattern like `https://*.example.com/*` will still match any |
| 131 | subdomain. This is extremely dangerous on shared hosting platforms |
| 132 | (e.g., `https://*.github.io/*` trusts every user's site on the |
| 133 | entire platform). |
| 134 | -- |
| 135 | + |
| 136 | Before matching, both the advertised URL and the pattern are |
| 137 | normalized: the scheme and host are lowercased, percent-encoded |
| 138 | characters are decoded where possible, and path segments like `..` |
| 139 | are resolved. The port must also match exactly (e.g., |
| 140 | `https://example.com:8080/*` will not match a URL advertised on |
| 141 | port 9999). The username and password components of the URL are |
| 142 | ignored during matching. Note that embedding credentials in URLs is |
| 143 | discouraged. Passing authentication tokens via the `token` field of |
| 144 | the `promisor-remote` capability is strongly preferred. |
| 145 | + |
| 146 | The glob pattern can optionally be prefixed with a remote name and an |
| 147 | equals sign (e.g., `cdn=https://cdn.example.com/*`). If such a prefix |
| 148 | is provided, accepted remotes will be saved under that name. If no |
| 149 | such prefix is provided, a safe remote name will be automatically |
| 150 | generated by sanitizing the URL and prefixing it with |
| 151 | `promisor-auto-`. |
| 152 | + |
| 153 | If a remote with the chosen name already exists but points to a |
| 154 | different URL, Git will append a numeric suffix (e.g., `-1`, `-2`) to |
| 155 | the name to prevent overwriting existing configurations. You should |
| 156 | make sure that this doesn't happen often though, as remotes will be |
| 157 | rejected if the numeric suffix increases too much. In all cases, the |
| 158 | original name advertised by the server is recorded in the |
| 159 | `remote.<name>.advertisedAs` configuration variable for tracing and |
| 160 | debugging purposes. |
| 161 | + |
| 162 | For the security implications of accepting a promisor remote, see the |
| 163 | documentation of `promisor.acceptFromServer`. For details on the |
| 164 | protocol, see linkgit:gitprotocol-v2[5]. |
| 165 | |
| 166 | promisor.checkFields:: |
| 167 | A comma or space separated list of additional remote related |
| 168 | field names. A client checks if the values of these fields |
| 169 | transmitted by a server correspond to the values of these |
| 170 | fields in its own configuration before accepting a promisor |
| 171 | remote. Currently, "partialCloneFilter" and "token" are the |
| 172 | only supported field names. |
| 173 | + |
| 174 | If one of these field names (e.g., "token") is being checked for an |
| 175 | advertised promisor remote (e.g., "foo"), three conditions must be met |
| 176 | for the check of this specific field to pass: |
| 177 | + |
| 178 | -- |
| 179 | 1. The corresponding local configuration (e.g., `remote.foo.token`) |
| 180 | must be set. |
| 181 | 2. The server must advertise the "token" field for remote "foo". |
| 182 | 3. The value of the locally configured `remote.foo.token` must exactly |
| 183 | match the value advertised by the server for the "token" field. |
| 184 | -- |
| 185 | + |
| 186 | If any of these conditions is not met for any field name listed in |
| 187 | `promisor.checkFields`, the advertised remote "foo" is rejected. |
| 188 | + |
| 189 | For the "partialCloneFilter" field, this allows the client to ensure |
| 190 | that the server's filter matches what it expects locally, preventing |
| 191 | inconsistencies in filtering behavior. For the "token" field, this can |
| 192 | be used to verify that authentication credentials match expected |
| 193 | values. |
| 194 | + |
| 195 | Field values are compared case-sensitively. |
| 196 | + |
| 197 | The "name" and "url" fields are always checked according to the |
| 198 | `promisor.acceptFromServer` policy, independently of this setting. |
| 199 | + |
| 200 | The field names and values should be passed by the server through the |
| 201 | "promisor-remote" capability by using the `promisor.sendFields` config |
| 202 | variable. The fields are checked only if the |
| 203 | `promisor.acceptFromServer` config variable is not set to "None". If |
| 204 | set to "None", this config variable has no effect. See |
| 205 | linkgit:gitprotocol-v2[5]. |
| 206 | |
| 207 | promisor.storeFields:: |
| 208 | A comma or space separated list of additional remote related |
| 209 | field names. If a client accepts an advertised remote, the |
| 210 | client will store the values associated with these field names |
| 211 | taken from the remote advertisement into its configuration, |
| 212 | and then reload its remote configuration. Currently, |
| 213 | "partialCloneFilter" and "token" are the only supported field |
| 214 | names. |
| 215 | + |
| 216 | For example if a server advertises "partialCloneFilter=blob:limit=20k" |
| 217 | for remote "foo", and that remote is accepted, then "blob:limit=20k" |
| 218 | will be stored for the "remote.foo.partialCloneFilter" configuration |
| 219 | variable. |
| 220 | + |
| 221 | If the new field value from an advertised remote is the same as the |
| 222 | existing field value for that remote on the client side, then no |
| 223 | change is made to the client configuration though. |
| 224 | + |
| 225 | When a new value is stored, a message is printed to standard error to |
| 226 | let users know about this. |
| 227 | + |
| 228 | Note that for security reasons, if the remote is not already |
| 229 | configured on the client side, nothing will be stored for that |
| 230 | remote. In any case, no new remote will be created and no URL will be |
| 231 | stored. |
| 232 | + |
| 233 | Before storing a partial clone filter, it's parsed to check it's |
| 234 | valid. If it's not, a warning is emitted and it's not stored. |
| 235 | + |
| 236 | Before storing a token, a check is performed to ensure it contains no |
| 237 | control character. If the check fails, a warning is emitted and it's |
| 238 | not stored. |