| 1 | gitcredentials(7) |
| 2 | ================= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | gitcredentials - Providing usernames and passwords to Git |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | ------------------ |
| 11 | git config credential.https://example.com.username myusername |
| 12 | git config credential.helper "$helper $options" |
| 13 | ------------------ |
| 14 | |
| 15 | DESCRIPTION |
| 16 | ----------- |
| 17 | |
| 18 | Git will sometimes need credentials from the user in order to perform |
| 19 | operations; for example, it may need to ask for a username and password |
| 20 | in order to access a remote repository over HTTP. Some remotes accept |
| 21 | a personal access token or OAuth access token as a password. This |
| 22 | manual describes the mechanisms Git uses to request these credentials, |
| 23 | as well as some features to avoid inputting these credentials repeatedly. |
| 24 | |
| 25 | REQUESTING CREDENTIALS |
| 26 | ---------------------- |
| 27 | |
| 28 | Without any credential helpers defined, Git will try the following |
| 29 | strategies to ask the user for usernames and passwords: |
| 30 | |
| 31 | 1. If the `GIT_ASKPASS` environment variable is set, the program |
| 32 | specified by the variable is invoked. A suitable prompt is provided |
| 33 | to the program on the command line, and the user's input is read |
| 34 | from its standard output. |
| 35 | |
| 36 | 2. Otherwise, if the `core.askPass` configuration variable is set, its |
| 37 | value is used as above. |
| 38 | |
| 39 | 3. Otherwise, if the `SSH_ASKPASS` environment variable is set, its |
| 40 | value is used as above. |
| 41 | |
| 42 | 4. Otherwise, the user is prompted on the terminal. |
| 43 | |
| 44 | AVOIDING REPETITION |
| 45 | ------------------- |
| 46 | |
| 47 | It can be cumbersome to input the same credentials over and over. Git |
| 48 | provides two methods to reduce this annoyance: |
| 49 | |
| 50 | 1. Static configuration of usernames for a given authentication context. |
| 51 | |
| 52 | 2. Credential helpers to cache or store passwords, or to interact with |
| 53 | a system password wallet or keychain. |
| 54 | |
| 55 | The first is simple and appropriate if you do not have secure storage available |
| 56 | for a password. It is generally configured by adding this to your config: |
| 57 | |
| 58 | --------------------------------------- |
| 59 | [credential "https://example.com"] |
| 60 | username = me |
| 61 | --------------------------------------- |
| 62 | |
| 63 | Credential helpers, on the other hand, are external programs from which Git can |
| 64 | request both usernames and passwords; they typically interface with secure |
| 65 | storage provided by the OS or other programs. Alternatively, a |
| 66 | credential-generating helper might generate credentials for certain servers via |
| 67 | some API. |
| 68 | |
| 69 | To use a helper, you must first select one to use (see below for a list). |
| 70 | |
| 71 | You may also have third-party helpers installed; search for |
| 72 | `credential-*` in the output of `git help -a`, and consult the |
| 73 | documentation of individual helpers. Once you have selected a helper, |
| 74 | you can tell Git to use it by putting its name into the |
| 75 | credential.helper variable. |
| 76 | |
| 77 | 1. Find a helper. |
| 78 | + |
| 79 | ------------------------------------------- |
| 80 | $ git help -a | grep credential- |
| 81 | credential-foo |
| 82 | ------------------------------------------- |
| 83 | |
| 84 | 2. Read its description. |
| 85 | + |
| 86 | ------------------------------------------- |
| 87 | $ git help credential-foo |
| 88 | ------------------------------------------- |
| 89 | |
| 90 | 3. Tell Git to use it. |
| 91 | + |
| 92 | ------------------------------------------- |
| 93 | $ git config --global credential.helper foo |
| 94 | ------------------------------------------- |
| 95 | |
| 96 | === Available helpers |
| 97 | |
| 98 | Git currently includes the following helpers: |
| 99 | |
| 100 | cache:: |
| 101 | |
| 102 | Cache credentials in memory for a short period of time. See |
| 103 | linkgit:git-credential-cache[1] for details. |
| 104 | |
| 105 | store:: |
| 106 | |
| 107 | Store credentials indefinitely on disk. See |
| 108 | linkgit:git-credential-store[1] for details. |
| 109 | |
| 110 | Popular helpers with secure persistent storage include: |
| 111 | |
| 112 | - git-credential-libsecret (Linux) |
| 113 | |
| 114 | - git-credential-osxkeychain (macOS) |
| 115 | |
| 116 | - git-credential-wincred (Windows) |
| 117 | |
| 118 | - https://github.com/git-ecosystem/git-credential-manager[Git Credential Manager] (cross platform, included in Git for Windows) |
| 119 | |
| 120 | The community maintains a comprehensive list of Git credential helpers at |
| 121 | https://git-scm.com/doc/credential-helpers. |
| 122 | |
| 123 | === OAuth |
| 124 | |
| 125 | An alternative to inputting passwords or personal access tokens is to use an |
| 126 | OAuth credential helper. Initial authentication opens a browser window to the |
| 127 | host. Subsequent authentication happens in the background. Many popular Git |
| 128 | hosts support OAuth. |
| 129 | |
| 130 | Popular helpers with OAuth support include: |
| 131 | |
| 132 | - https://github.com/git-ecosystem/git-credential-manager[Git Credential Manager] (cross platform, included in Git for Windows) |
| 133 | |
| 134 | - https://github.com/hickford/git-credential-oauth[git-credential-oauth] (cross platform, included in many Linux distributions) |
| 135 | |
| 136 | CREDENTIAL CONTEXTS |
| 137 | ------------------- |
| 138 | |
| 139 | Git considers each credential to have a context defined by a URL. This context |
| 140 | is used to look up context-specific configuration, and is passed to any |
| 141 | helpers, which may use it as an index into secure storage. |
| 142 | |
| 143 | For instance, imagine we are accessing `https://example.com/foo.git`. When Git |
| 144 | looks into a config file to see if a section matches this context, it will |
| 145 | consider the two a match if the context is a more-specific subset of the |
| 146 | pattern in the config file. For example, if you have this in your config file: |
| 147 | |
| 148 | -------------------------------------- |
| 149 | [credential "https://example.com"] |
| 150 | username = foo |
| 151 | -------------------------------------- |
| 152 | |
| 153 | then we will match: both protocols are the same and both hosts are the same. |
| 154 | However, this context would not match: |
| 155 | |
| 156 | -------------------------------------- |
| 157 | [credential "https://kernel.org"] |
| 158 | username = foo |
| 159 | -------------------------------------- |
| 160 | |
| 161 | because the hostnames differ. Nor would it match `foo.example.com`; Git |
| 162 | compares hostnames exactly, without considering whether two hosts are part of |
| 163 | the same domain. Likewise, a config entry for `http://example.com` would not |
| 164 | match: Git compares the protocols exactly. However, you may use wildcards in |
| 165 | the domain name and other pattern matching techniques as with the `http.<URL>.*` |
| 166 | options. |
| 167 | |
| 168 | If the "pattern" URL does include a path component, then this must match |
| 169 | as a prefix path: the context `https://example.com/bar` will match a config |
| 170 | entry for `https://example.com/bar/baz.git` but will not match a config entry for |
| 171 | `https://example.com/other/repo.git` or `https://example.com/barry/repo.git` |
| 172 | (even though it is a string prefix). |
| 173 | |
| 174 | |
| 175 | CONFIGURATION OPTIONS |
| 176 | --------------------- |
| 177 | |
| 178 | Options for a credential context can be configured either in |
| 179 | `credential.*` (which applies to all credentials), or |
| 180 | `credential.<URL>.*`, where <URL> matches the context as described |
| 181 | above. |
| 182 | |
| 183 | The following options are available in either location: |
| 184 | |
| 185 | helper:: |
| 186 | |
| 187 | The name of an external credential helper, and any associated options. |
| 188 | If the helper name is not an absolute path, then the string `git |
| 189 | credential-` is prepended. The resulting string is executed by the |
| 190 | shell (so, for example, setting this to `foo --option=bar` will execute |
| 191 | `git credential-foo --option=bar` via the shell. See the manual of |
| 192 | specific helpers for examples of their use. |
| 193 | + |
| 194 | If there are multiple instances of the `credential.helper` configuration |
| 195 | variable, each helper will be tried in turn, and may provide a username, |
| 196 | password, or nothing. Once Git has acquired both a username and a |
| 197 | non-expired password, no more helpers will be tried. |
| 198 | + |
| 199 | If `credential.helper` is configured to the empty string, this resets |
| 200 | the helper list to empty (so you may override a helper set by a |
| 201 | lower-priority config file by configuring the empty-string helper, |
| 202 | followed by whatever set of helpers you would like). |
| 203 | |
| 204 | username:: |
| 205 | |
| 206 | A default username, if one is not provided in the URL. |
| 207 | |
| 208 | useHttpPath:: |
| 209 | |
| 210 | By default, Git does not consider the "path" component of an http URL |
| 211 | to be worth matching via external helpers. This means that a credential |
| 212 | stored for `https://example.com/foo.git` will also be used for |
| 213 | `https://example.com/bar.git`. If you do want to distinguish these |
| 214 | cases, set this option to `true`. |
| 215 | |
| 216 | |
| 217 | CUSTOM HELPERS |
| 218 | -------------- |
| 219 | |
| 220 | You can write your own custom helpers to interface with any system in |
| 221 | which you keep credentials. |
| 222 | |
| 223 | Credential helpers are programs executed by Git to fetch or save |
| 224 | credentials from and to long-term storage (where "long-term" is simply |
| 225 | longer than a single Git process; e.g., credentials may be stored |
| 226 | in-memory for a few minutes, or indefinitely on disk). |
| 227 | |
| 228 | Each helper is specified by a single string in the configuration |
| 229 | variable `credential.helper` (and others, see linkgit:git-config[1]). |
| 230 | The string is transformed by Git into a command to be executed using |
| 231 | these rules: |
| 232 | |
| 233 | 1. If the helper string begins with "!", it is considered a shell |
| 234 | snippet, and everything after the "!" becomes the command. |
| 235 | |
| 236 | 2. Otherwise, if the helper string begins with an absolute path, the |
| 237 | verbatim helper string becomes the command. |
| 238 | |
| 239 | 3. Otherwise, the string "git credential-" is prepended to the helper |
| 240 | string, and the result becomes the command. |
| 241 | |
| 242 | The resulting command then has an "operation" argument appended to it |
| 243 | (see below for details), and the result is executed by the shell. |
| 244 | |
| 245 | Here are some example specifications: |
| 246 | |
| 247 | ---------------------------------------------------- |
| 248 | # run "git credential-foo" |
| 249 | [credential] |
| 250 | helper = foo |
| 251 | |
| 252 | # same as above, but pass an argument to the helper |
| 253 | [credential] |
| 254 | helper = "foo --bar=baz" |
| 255 | |
| 256 | # the arguments are parsed by the shell, so use shell |
| 257 | # quoting if necessary |
| 258 | [credential] |
| 259 | helper = "foo --bar='whitespace arg'" |
| 260 | |
| 261 | # store helper (discouraged) with custom location for the db file; |
| 262 | # use `--file ~/.git-secret.txt`, rather than `--file=~/.git-secret.txt`, |
| 263 | # to allow the shell to expand tilde to the home directory. |
| 264 | [credential] |
| 265 | helper = "store --file ~/.git-secret.txt" |
| 266 | |
| 267 | # you can also use an absolute path, which will not use the git wrapper |
| 268 | [credential] |
| 269 | helper = "/path/to/my/helper --with-arguments" |
| 270 | |
| 271 | # or you can specify your own shell snippet |
| 272 | [credential "https://example.com"] |
| 273 | username = your_user |
| 274 | helper = "!f() { test \"$1\" = get && echo \"password=$(cat $HOME/.secret)\"; }; f" |
| 275 | ---------------------------------------------------- |
| 276 | |
| 277 | Generally speaking, rule (3) above is the simplest for users to specify. |
| 278 | Authors of credential helpers should make an effort to assist their |
| 279 | users by naming their program "git-credential-$NAME", and putting it in |
| 280 | the `$PATH` or `$GIT_EXEC_PATH` during installation, which will allow a |
| 281 | user to enable it with `git config credential.helper $NAME`. |
| 282 | |
| 283 | When a helper is executed, it will have one "operation" argument |
| 284 | appended to its command line, which is one of: |
| 285 | |
| 286 | `get`:: |
| 287 | |
| 288 | Return a matching credential, if any exists. |
| 289 | |
| 290 | `store`:: |
| 291 | |
| 292 | Store the credential, if applicable to the helper. |
| 293 | |
| 294 | `erase`:: |
| 295 | |
| 296 | Remove matching credentials, if any, from the helper's storage. |
| 297 | |
| 298 | The details of the credential will be provided on the helper's stdin |
| 299 | stream. The exact format is the same as the input/output format of the |
| 300 | `git credential` plumbing command (see the section `INPUT/OUTPUT |
| 301 | FORMAT` in linkgit:git-credential[1] for a detailed specification). |
| 302 | |
| 303 | For a `get` operation, the helper should produce a list of attributes on |
| 304 | stdout in the same format (see linkgit:git-credential[1] for common |
| 305 | attributes). A helper is free to produce a subset, or even no values at |
| 306 | all if it has nothing useful to provide. Any provided attributes will |
| 307 | overwrite those already known about by Git's credential subsystem. |
| 308 | Unrecognised attributes are silently discarded. |
| 309 | |
| 310 | While it is possible to override all attributes, well behaving helpers |
| 311 | should refrain from doing so for any attribute other than username and |
| 312 | password. |
| 313 | |
| 314 | If a helper outputs a `quit` attribute with a value of `true` or `1`, |
| 315 | no further helpers will be consulted, nor will the user be prompted |
| 316 | (if no credential has been provided, the operation will then fail). |
| 317 | |
| 318 | Similarly, no more helpers will be consulted once both username and |
| 319 | password had been provided. |
| 320 | |
| 321 | For a `store` or `erase` operation, the helper's output is ignored. |
| 322 | |
| 323 | If a helper fails to perform the requested operation or needs to notify |
| 324 | the user of a potential issue, it may write to stderr. |
| 325 | |
| 326 | If it does not support the requested operation (e.g., a read-only store |
| 327 | or generator), it should silently ignore the request. |
| 328 | |
| 329 | If a helper receives any other operation, it should silently ignore the |
| 330 | request. This leaves room for future operations to be added (older |
| 331 | helpers will just ignore the new requests). |
| 332 | |
| 333 | GIT |
| 334 | --- |
| 335 | Part of the linkgit:git[1] suite |