| 1 | http.proxy:: |
| 2 | Override the HTTP proxy, normally configured using the 'http_proxy', |
| 3 | 'https_proxy', and 'all_proxy' environment variables (see `curl(1)`). In |
| 4 | addition to the syntax understood by curl, it is possible to specify a |
| 5 | proxy string with a user name but no password, in which case git will |
| 6 | attempt to acquire one in the same way it does for other credentials. See |
| 7 | linkgit:gitcredentials[7] for more information. The syntax thus is |
| 8 | '[protocol://][user[:password]@]proxyhost[:port][/path]'. This can be |
| 9 | overridden on a per-remote basis; see remote.<name>.proxy |
| 10 | + |
| 11 | Any proxy, however configured, must be completely transparent and must not |
| 12 | modify, transform, or buffer the request or response in any way. Proxies which |
| 13 | are not completely transparent are known to cause various forms of breakage |
| 14 | with Git. |
| 15 | |
| 16 | http.proxyAuthMethod:: |
| 17 | Set the method with which to authenticate against the HTTP proxy. This |
| 18 | only takes effect if the configured proxy string contains a user name part |
| 19 | (i.e. is of the form 'user@host' or 'user@host:port'). This can be |
| 20 | overridden on a per-remote basis; see `remote.<name>.proxyAuthMethod`. |
| 21 | Both can be overridden by the `GIT_HTTP_PROXY_AUTHMETHOD` environment |
| 22 | variable. Possible values are: |
| 23 | + |
| 24 | -- |
| 25 | * `anyauth` - Automatically pick a suitable authentication method. It is |
| 26 | assumed that the proxy answers an unauthenticated request with a 407 |
| 27 | status code and one or more Proxy-authenticate headers with supported |
| 28 | authentication methods. This is the default. |
| 29 | * `basic` - HTTP Basic authentication |
| 30 | * `digest` - HTTP Digest authentication; this prevents the password from being |
| 31 | transmitted to the proxy in clear text |
| 32 | * `negotiate` - GSS-Negotiate authentication (compare the --negotiate option |
| 33 | of `curl(1)`) |
| 34 | * `ntlm` - NTLM authentication (compare the --ntlm option of `curl(1)`) |
| 35 | -- |
| 36 | |
| 37 | http.proxySSLCert:: |
| 38 | The pathname of a file that stores a client certificate to use to authenticate |
| 39 | with an HTTPS proxy. Can be overridden by the `GIT_PROXY_SSL_CERT` environment |
| 40 | variable. |
| 41 | |
| 42 | http.proxySSLKey:: |
| 43 | The pathname of a file that stores a private key to use to authenticate with |
| 44 | an HTTPS proxy. Can be overridden by the `GIT_PROXY_SSL_KEY` environment |
| 45 | variable. |
| 46 | |
| 47 | http.proxySSLCertPasswordProtected:: |
| 48 | Enable Git's password prompt for the proxy SSL certificate. Otherwise OpenSSL |
| 49 | will prompt the user, possibly many times, if the certificate or private key |
| 50 | is encrypted. Can be overridden by the `GIT_PROXY_SSL_CERT_PASSWORD_PROTECTED` |
| 51 | environment variable. |
| 52 | |
| 53 | http.proxySSLCAInfo:: |
| 54 | Pathname to the file containing the certificate bundle that should be used to |
| 55 | verify the proxy with when using an HTTPS proxy. Can be overridden by the |
| 56 | `GIT_PROXY_SSL_CAINFO` environment variable. |
| 57 | |
| 58 | http.emptyAuth:: |
| 59 | Attempt authentication without seeking a username or password. This |
| 60 | can be used to attempt GSS-Negotiate authentication without specifying |
| 61 | a username in the URL, as libcurl normally requires a username for |
| 62 | authentication. Possible values are: |
| 63 | + |
| 64 | -- |
| 65 | * `auto` (default) - Send empty credentials only if the server's 401 response |
| 66 | advertises an authentication mechanism that requires them (such as |
| 67 | GSS-Negotiate); otherwise fall back to prompting via the credential helper. |
| 68 | * `true` - Always send empty credentials on the very first request, before |
| 69 | receiving any 401 response from the server. |
| 70 | * `false` - Never send empty credentials. Mechanisms that require |
| 71 | empty credentials or an explicit username, such as GSS-Negotiate, will not |
| 72 | work. |
| 73 | -- |
| 74 | |
| 75 | http.proactiveAuth:: |
| 76 | Attempt authentication without first making an unauthenticated attempt and |
| 77 | receiving a 401 response. This can be used to ensure that all requests are |
| 78 | authenticated. If `http.emptyAuth` is set to true, this value has no effect. |
| 79 | + |
| 80 | If the credential helper used specifies an authentication scheme (i.e., via the |
| 81 | `authtype` field), that value will be used; if a username and password is |
| 82 | provided without a scheme, then Basic authentication is used. The value of the |
| 83 | option determines the scheme requested from the helper. Possible values are: |
| 84 | + |
| 85 | -- |
| 86 | * `basic` - Request Basic authentication from the helper. |
| 87 | * `auto` - Allow the helper to pick an appropriate scheme. |
| 88 | * `none` - Disable proactive authentication. |
| 89 | -- |
| 90 | + |
| 91 | Note that TLS should always be used with this configuration, since otherwise it |
| 92 | is easy to accidentally expose plaintext credentials if Basic authentication |
| 93 | is selected. |
| 94 | |
| 95 | http.delegation:: |
| 96 | Control GSSAPI credential delegation. The delegation is disabled |
| 97 | by default in libcurl since version 7.21.7. Set parameter to tell |
| 98 | the server what it is allowed to delegate when it comes to user |
| 99 | credentials. Used with GSS/kerberos. Possible values are: |
| 100 | + |
| 101 | -- |
| 102 | * `none` - Don't allow any delegation. |
| 103 | * `policy` - Delegates if and only if the OK-AS-DELEGATE flag is set in the |
| 104 | Kerberos service ticket, which is a matter of realm policy. |
| 105 | * `always` - Unconditionally allow the server to delegate. |
| 106 | -- |
| 107 | |
| 108 | |
| 109 | http.extraHeader:: |
| 110 | Pass an additional HTTP header when communicating with a server. If |
| 111 | more than one such entry exists, all of them are added as extra |
| 112 | headers. To allow overriding the settings inherited from the system |
| 113 | config, an empty value will reset the extra headers to the empty list. |
| 114 | |
| 115 | http.cookieFile:: |
| 116 | The pathname of a file containing previously stored cookie lines, |
| 117 | which should be used |
| 118 | in the Git http session, if they match the server. The file format |
| 119 | of the file to read cookies from should be plain HTTP headers or |
| 120 | the Netscape/Mozilla cookie file format (see `curl(1)`). |
| 121 | Set it to an empty string, to accept only new cookies from |
| 122 | the server and send them back in successive requests within same |
| 123 | connection. |
| 124 | NOTE that the file specified with http.cookieFile is used only as |
| 125 | input unless http.saveCookies is set. |
| 126 | |
| 127 | http.saveCookies:: |
| 128 | If set, store cookies received during requests to the file specified by |
| 129 | http.cookieFile. Has no effect if http.cookieFile is unset, or set to |
| 130 | an empty string. |
| 131 | |
| 132 | http.version:: |
| 133 | Use the specified HTTP protocol version when communicating with a server. |
| 134 | If you want to force the default. The available and default version depend |
| 135 | on libcurl. Currently the possible values of |
| 136 | this option are: |
| 137 | |
| 138 | - HTTP/2 |
| 139 | - HTTP/1.1 |
| 140 | |
| 141 | http.curloptResolve:: |
| 142 | Hostname resolution information that will be used first by |
| 143 | libcurl when sending HTTP requests. This information should |
| 144 | be in one of the following formats: |
| 145 | |
| 146 | - [+]HOST:PORT:ADDRESS[,ADDRESS] |
| 147 | - -HOST:PORT |
| 148 | |
| 149 | + |
| 150 | The first format redirects all requests to the given `HOST:PORT` |
| 151 | to the provided `ADDRESS`(s). The second format clears all |
| 152 | previous config values for that `HOST:PORT` combination. To |
| 153 | allow easy overriding of all the settings inherited from the |
| 154 | system config, an empty value will reset all resolution |
| 155 | information to the empty list. |
| 156 | |
| 157 | http.sslVersion:: |
| 158 | The SSL version to use when negotiating an SSL connection, if you |
| 159 | want to force the default. The available and default version |
| 160 | depend on whether libcurl was built against NSS or OpenSSL and the |
| 161 | particular configuration of the crypto library in use. Internally |
| 162 | this sets the 'CURLOPT_SSL_VERSION' option; see the libcurl |
| 163 | documentation for more details on the format of this option and |
| 164 | for the ssl version supported. Currently the possible values of |
| 165 | this option are: |
| 166 | |
| 167 | - sslv2 |
| 168 | - sslv3 |
| 169 | - tlsv1 |
| 170 | - tlsv1.0 |
| 171 | - tlsv1.1 |
| 172 | - tlsv1.2 |
| 173 | - tlsv1.3 |
| 174 | |
| 175 | + |
| 176 | Can be overridden by the `GIT_SSL_VERSION` environment variable. |
| 177 | To force git to use libcurl's default ssl version and ignore any |
| 178 | explicit http.sslversion option, set `GIT_SSL_VERSION` to the |
| 179 | empty string. |
| 180 | |
| 181 | http.sslCipherList:: |
| 182 | A list of SSL ciphers to use when negotiating an SSL connection. |
| 183 | The available ciphers depend on whether libcurl was built against |
| 184 | NSS or OpenSSL and the particular configuration of the crypto |
| 185 | library in use. Internally this sets the 'CURLOPT_SSL_CIPHER_LIST' |
| 186 | option; see the libcurl documentation for more details on the format |
| 187 | of this list. |
| 188 | + |
| 189 | Can be overridden by the `GIT_SSL_CIPHER_LIST` environment variable. |
| 190 | To force git to use libcurl's default cipher list and ignore any |
| 191 | explicit http.sslCipherList option, set `GIT_SSL_CIPHER_LIST` to the |
| 192 | empty string. |
| 193 | |
| 194 | http.sslVerify:: |
| 195 | Whether to verify the SSL certificate when fetching or pushing |
| 196 | over HTTPS. Defaults to true. Can be overridden by the |
| 197 | `GIT_SSL_NO_VERIFY` environment variable. |
| 198 | |
| 199 | http.sslCert:: |
| 200 | File containing the SSL certificate when fetching or pushing |
| 201 | over HTTPS. Can be overridden by the `GIT_SSL_CERT` environment |
| 202 | variable. |
| 203 | |
| 204 | http.sslKey:: |
| 205 | File containing the SSL private key when fetching or pushing |
| 206 | over HTTPS. Can be overridden by the `GIT_SSL_KEY` environment |
| 207 | variable. |
| 208 | |
| 209 | http.sslCertPasswordProtected:: |
| 210 | Enable Git's password prompt for the SSL certificate. Otherwise |
| 211 | OpenSSL will prompt the user, possibly many times, if the |
| 212 | certificate or private key is encrypted. Can be overridden by the |
| 213 | `GIT_SSL_CERT_PASSWORD_PROTECTED` environment variable. |
| 214 | |
| 215 | http.sslCAInfo:: |
| 216 | File containing the certificates to verify the peer with when |
| 217 | fetching or pushing over HTTPS. Can be overridden by the |
| 218 | `GIT_SSL_CAINFO` environment variable. |
| 219 | |
| 220 | http.sslCAPath:: |
| 221 | Path containing files with the CA certificates to verify the peer |
| 222 | with when fetching or pushing over HTTPS. Can be overridden |
| 223 | by the `GIT_SSL_CAPATH` environment variable. |
| 224 | |
| 225 | http.sslBackend:: |
| 226 | Name of the SSL backend to use (e.g. "openssl" or "schannel"). |
| 227 | This option is ignored if cURL lacks support for choosing the SSL |
| 228 | backend at runtime. |
| 229 | |
| 230 | http.sslCertType:: |
| 231 | Type of client certificate used when fetching or pushing over HTTPS. |
| 232 | "PEM", "DER" are supported when using openssl or gnutls backends. "P12" |
| 233 | is supported on "openssl", "schannel", "securetransport", and gnutls 8.11+. |
| 234 | See also libcurl `CURLOPT_SSLCERTTYPE`. Can be overridden by the |
| 235 | `GIT_SSL_CERT_TYPE` environment variable. |
| 236 | |
| 237 | http.sslKeyType:: |
| 238 | Type of client private key used when fetching or pushing over HTTPS. (e.g. |
| 239 | "PEM", "DER", or "ENG"). Only applicable when using "openssl" backend. "DER" |
| 240 | is not supported with openssl. Particularly useful when set to "ENG" for |
| 241 | authenticating with PKCS#11 tokens, with a PKCS#11 URL in sslCert option. |
| 242 | See also libcurl `CURLOPT_SSLKEYTYPE`. Can be overridden by the |
| 243 | `GIT_SSL_KEY_TYPE` environment variable. |
| 244 | |
| 245 | http.schannelCheckRevoke:: |
| 246 | Used to enforce or disable certificate revocation checks in cURL |
| 247 | when http.sslBackend is set to "schannel". Defaults to `true` if |
| 248 | unset. Only necessary to disable this if Git consistently errors |
| 249 | and the message is about checking the revocation status of a |
| 250 | certificate. This option is ignored if cURL lacks support for |
| 251 | setting the relevant SSL option at runtime. |
| 252 | |
| 253 | http.schannelUseSSLCAInfo:: |
| 254 | As of cURL v7.60.0, the Secure Channel backend can use the |
| 255 | certificate bundle provided via `http.sslCAInfo`, but that would |
| 256 | override the Windows Certificate Store. Since this is not desirable |
| 257 | by default, Git will tell cURL not to use that bundle by default |
| 258 | when the `schannel` backend was configured via `http.sslBackend`, |
| 259 | unless `http.schannelUseSSLCAInfo` overrides this behavior. |
| 260 | |
| 261 | http.pinnedPubkey:: |
| 262 | Public key of the https service. It may either be the filename of |
| 263 | a PEM or DER encoded public key file or a string starting with |
| 264 | 'sha256//' followed by the base64 encoded sha256 hash of the |
| 265 | public key. See also libcurl 'CURLOPT_PINNEDPUBLICKEY'. git will |
| 266 | exit with an error if this option is set but not supported by |
| 267 | cURL. |
| 268 | |
| 269 | http.sslTry:: |
| 270 | Attempt to use AUTH SSL/TLS and encrypted data transfers |
| 271 | when connecting via regular FTP protocol. This might be needed |
| 272 | if the FTP server requires it for security reasons or you wish |
| 273 | to connect securely whenever remote FTP server supports it. |
| 274 | Default is false since it might trigger certificate verification |
| 275 | errors on misconfigured servers. |
| 276 | |
| 277 | http.maxRequests:: |
| 278 | How many HTTP requests to launch in parallel. Can be overridden |
| 279 | by the `GIT_HTTP_MAX_REQUESTS` environment variable. Default is 5. |
| 280 | |
| 281 | http.minSessions:: |
| 282 | The number of curl sessions (counted across slots) to be kept across |
| 283 | requests. They will not be ended with curl_easy_cleanup() until |
| 284 | http_cleanup() is invoked. If USE_CURL_MULTI is not defined, this |
| 285 | value will be capped at 1. Defaults to 1. |
| 286 | |
| 287 | http.postBuffer:: |
| 288 | Maximum size in bytes of the buffer used by smart HTTP |
| 289 | transports when POSTing data to the remote system. |
| 290 | For requests larger than this buffer size, HTTP/1.1 and |
| 291 | Transfer-Encoding: chunked is used to avoid creating a |
| 292 | massive pack file locally. Default is 1 MiB, which is |
| 293 | sufficient for most requests. |
| 294 | + |
| 295 | Note that raising this limit is only effective for disabling chunked |
| 296 | transfer encoding and therefore should be used only where the remote |
| 297 | server or a proxy only supports HTTP/1.0 or is noncompliant with the |
| 298 | HTTP standard. Raising this is not, in general, an effective solution |
| 299 | for most push problems, but can increase memory consumption |
| 300 | significantly since the entire buffer is allocated even for small |
| 301 | pushes. |
| 302 | |
| 303 | http.lowSpeedLimit:: |
| 304 | http.lowSpeedTime:: |
| 305 | If the HTTP transfer speed, in bytes per second, is less than |
| 306 | 'http.lowSpeedLimit' for longer than 'http.lowSpeedTime' seconds, |
| 307 | the transfer is aborted. |
| 308 | Can be overridden by the `GIT_HTTP_LOW_SPEED_LIMIT` and |
| 309 | `GIT_HTTP_LOW_SPEED_TIME` environment variables. |
| 310 | |
| 311 | http.keepAliveIdle:: |
| 312 | Specifies how long in seconds to wait on an idle connection |
| 313 | before sending TCP keepalive probes (if supported by the OS). If |
| 314 | unset, curl's default value is used. Can be overridden by the |
| 315 | `GIT_HTTP_KEEPALIVE_IDLE` environment variable. |
| 316 | |
| 317 | http.keepAliveInterval:: |
| 318 | Specifies how long in seconds to wait between TCP keepalive |
| 319 | probes (if supported by the OS). If unset, curl's default value |
| 320 | is used. Can be overridden by the `GIT_HTTP_KEEPALIVE_INTERVAL` |
| 321 | environment variable. |
| 322 | |
| 323 | http.keepAliveCount:: |
| 324 | Specifies how many TCP keepalive probes to send before giving up |
| 325 | and terminating the connection (if supported by the OS). If |
| 326 | unset, curl's default value is used. Can be overridden by the |
| 327 | `GIT_HTTP_KEEPALIVE_COUNT` environment variable. |
| 328 | |
| 329 | http.retryAfter:: |
| 330 | Default wait time in seconds before retrying when a server returns |
| 331 | HTTP 429 (Too Many Requests) without a Retry-After header. |
| 332 | Defaults to 0 (retry immediately). When a Retry-After header is |
| 333 | present, its value takes precedence over this setting; however, |
| 334 | automatic use of the server-provided `Retry-After` header requires |
| 335 | libcurl 7.66.0 or later. On older versions, configure this setting |
| 336 | manually to control the retry delay. Can be overridden by the |
| 337 | `GIT_HTTP_RETRY_AFTER` environment variable. |
| 338 | See also `http.maxRetries` and `http.maxRetryTime`. |
| 339 | |
| 340 | http.maxRetries:: |
| 341 | Maximum number of times to retry after receiving HTTP 429 (Too Many |
| 342 | Requests) responses. Set to 0 (the default) to disable retries. |
| 343 | Can be overridden by the `GIT_HTTP_MAX_RETRIES` environment variable. |
| 344 | See also `http.retryAfter` and `http.maxRetryTime`. |
| 345 | |
| 346 | http.maxRetryTime:: |
| 347 | Maximum time in seconds to wait for a single retry attempt when |
| 348 | handling HTTP 429 (Too Many Requests) responses. If the server |
| 349 | requests a delay (via Retry-After header) or if `http.retryAfter` |
| 350 | is configured with a value that exceeds this maximum, Git will fail |
| 351 | immediately rather than waiting. Default is 300 seconds (5 minutes). |
| 352 | Can be overridden by the `GIT_HTTP_MAX_RETRY_TIME` environment |
| 353 | variable. See also `http.retryAfter` and `http.maxRetries`. |
| 354 | |
| 355 | http.noEPSV:: |
| 356 | A boolean which disables using of EPSV ftp command by curl. |
| 357 | This can be helpful with some "poor" ftp servers which don't |
| 358 | support EPSV mode. Can be overridden by the `GIT_CURL_FTP_NO_EPSV` |
| 359 | environment variable. Default is false (curl will use EPSV). |
| 360 | |
| 361 | http.userAgent:: |
| 362 | The HTTP USER_AGENT string presented to an HTTP server. The default |
| 363 | value represents the version of the Git client such as git/1.7.1. |
| 364 | This option allows you to override this value to a more common value |
| 365 | such as Mozilla/4.0. This may be necessary, for instance, if |
| 366 | connecting through a firewall that restricts HTTP connections to a set |
| 367 | of common USER_AGENT strings (but not including those like git/1.7.1). |
| 368 | Can be overridden by the `GIT_HTTP_USER_AGENT` environment variable. |
| 369 | |
| 370 | http.followRedirects:: |
| 371 | Whether git should follow HTTP redirects. If set to `true`, git |
| 372 | will transparently follow any redirect issued by a server it |
| 373 | encounters. If set to `false`, git will treat all redirects as |
| 374 | errors. If set to `initial`, git will follow redirects only for |
| 375 | the initial request to a remote, but not for subsequent |
| 376 | follow-up HTTP requests. Since git uses the redirected URL as |
| 377 | the base for the follow-up requests, this is generally |
| 378 | sufficient. The default is `initial`. |
| 379 | |
| 380 | http.<url>.*:: |
| 381 | Any of the http.* options above can be applied selectively to some URLs. |
| 382 | For a config key to match a URL, each element of the config key is |
| 383 | compared to that of the URL, in the following order: |
| 384 | + |
| 385 | -- |
| 386 | . Scheme (e.g., `https` in `https://example.com/`). This field |
| 387 | must match exactly between the config key and the URL. |
| 388 | |
| 389 | . Host/domain name (e.g., `example.com` in `https://example.com/`). |
| 390 | This field must match between the config key and the URL. It is |
| 391 | possible to specify a `*` as part of the host name to match all subdomains |
| 392 | at this level. `https://*.example.com/` for example would match |
| 393 | `https://foo.example.com/`, but not `https://foo.bar.example.com/`. |
| 394 | |
| 395 | . Port number (e.g., `8080` in `http://example.com:8080/`). |
| 396 | This field must match exactly between the config key and the URL. |
| 397 | Omitted port numbers are automatically converted to the correct |
| 398 | default for the scheme before matching. |
| 399 | |
| 400 | . Path (e.g., `repo.git` in `https://example.com/repo.git`). The |
| 401 | path field of the config key must match the path field of the URL |
| 402 | either exactly or as a prefix of slash-delimited path elements. This means |
| 403 | a config key with path `foo/` matches URL path `foo/bar`. A prefix can only |
| 404 | match on a slash (`/`) boundary. Longer matches take precedence (so a config |
| 405 | key with path `foo/bar` is a better match to URL path `foo/bar` than a config |
| 406 | key with just path `foo/`). |
| 407 | |
| 408 | . User name (e.g., `user` in `https://user@example.com/repo.git`). If |
| 409 | the config key has a user name it must match the user name in the |
| 410 | URL exactly. If the config key does not have a user name, that |
| 411 | config key will match a URL with any user name (including none), |
| 412 | but at a lower precedence than a config key with a user name. |
| 413 | -- |
| 414 | + |
| 415 | The list above is ordered by decreasing precedence; a URL that matches |
| 416 | a config key's path is preferred to one that matches its user name. For example, |
| 417 | if the URL is `https://user@example.com/foo/bar` a config key match of |
| 418 | `https://example.com/foo` will be preferred over a config key match of |
| 419 | `https://user@example.com`. |
| 420 | + |
| 421 | All URLs are normalized before attempting any matching (the password part, |
| 422 | if embedded in the URL, is always ignored for matching purposes) so that |
| 423 | equivalent URLs that are simply spelled differently will match properly. |
| 424 | Environment variable settings always override any matches. The URLs that are |
| 425 | matched against are those given directly to Git commands. This means any URLs |
| 426 | visited as a result of a redirection do not participate in matching. |