Jeff King | a6fc9fd | 2011-12-10 05:31:38 -0500 | [diff] [blame] | 1 | gitcredentials(7) |
| 2 | ================= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 6 | gitcredentials - providing usernames and passwords to Git |
Jeff King | a6fc9fd | 2011-12-10 05:31:38 -0500 | [diff] [blame] | 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. This manual describes |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 21 | the mechanisms Git uses to request these credentials, as well as some |
Jeff King | a6fc9fd | 2011-12-10 05:31:38 -0500 | [diff] [blame] | 22 | features to avoid inputting these credentials repeatedly. |
| 23 | |
| 24 | REQUESTING CREDENTIALS |
| 25 | ---------------------- |
| 26 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 27 | Without any credential helpers defined, Git will try the following |
Jeff King | a6fc9fd | 2011-12-10 05:31:38 -0500 | [diff] [blame] | 28 | strategies to ask the user for usernames and passwords: |
| 29 | |
| 30 | 1. If the `GIT_ASKPASS` environment variable is set, the program |
| 31 | specified by the variable is invoked. A suitable prompt is provided |
| 32 | to the program on the command line, and the user's input is read |
| 33 | from its standard output. |
| 34 | |
Nguyễn Thái Ngọc Duy | da0005b | 2015-03-11 16:32:45 -0400 | [diff] [blame] | 35 | 2. Otherwise, if the `core.askPass` configuration variable is set, its |
Jeff King | a6fc9fd | 2011-12-10 05:31:38 -0500 | [diff] [blame] | 36 | value is used as above. |
| 37 | |
| 38 | 3. Otherwise, if the `SSH_ASKPASS` environment variable is set, its |
| 39 | value is used as above. |
| 40 | |
| 41 | 4. Otherwise, the user is prompted on the terminal. |
| 42 | |
| 43 | AVOIDING REPETITION |
| 44 | ------------------- |
| 45 | |
| 46 | It can be cumbersome to input the same credentials over and over. Git |
| 47 | provides two methods to reduce this annoyance: |
| 48 | |
| 49 | 1. Static configuration of usernames for a given authentication context. |
| 50 | |
| 51 | 2. Credential helpers to cache or store passwords, or to interact with |
| 52 | a system password wallet or keychain. |
| 53 | |
| 54 | The first is simple and appropriate if you do not have secure storage available |
| 55 | for a password. It is generally configured by adding this to your config: |
| 56 | |
| 57 | --------------------------------------- |
| 58 | [credential "https://example.com"] |
| 59 | username = me |
| 60 | --------------------------------------- |
| 61 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 62 | Credential helpers, on the other hand, are external programs from which Git can |
Jeff King | a6fc9fd | 2011-12-10 05:31:38 -0500 | [diff] [blame] | 63 | request both usernames and passwords; they typically interface with secure |
| 64 | storage provided by the OS or other programs. |
| 65 | |
Jeff King | e277097 | 2011-12-10 05:34:14 -0500 | [diff] [blame] | 66 | To use a helper, you must first select one to use. Git currently |
| 67 | includes the following helpers: |
| 68 | |
| 69 | cache:: |
| 70 | |
| 71 | Cache credentials in memory for a short period of time. See |
| 72 | linkgit:git-credential-cache[1] for details. |
| 73 | |
Jeff King | 71e1b4b | 2011-12-10 05:34:44 -0500 | [diff] [blame] | 74 | store:: |
| 75 | |
| 76 | Store credentials indefinitely on disk. See |
| 77 | linkgit:git-credential-store[1] for details. |
| 78 | |
Jeff King | e277097 | 2011-12-10 05:34:14 -0500 | [diff] [blame] | 79 | You may also have third-party helpers installed; search for |
| 80 | `credential-*` in the output of `git help -a`, and consult the |
| 81 | documentation of individual helpers. Once you have selected a helper, |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 82 | you can tell Git to use it by putting its name into the |
Jeff King | a6fc9fd | 2011-12-10 05:31:38 -0500 | [diff] [blame] | 83 | credential.helper variable. |
| 84 | |
| 85 | 1. Find a helper. |
| 86 | + |
| 87 | ------------------------------------------- |
| 88 | $ git help -a | grep credential- |
| 89 | credential-foo |
| 90 | ------------------------------------------- |
| 91 | |
| 92 | 2. Read its description. |
| 93 | + |
| 94 | ------------------------------------------- |
| 95 | $ git help credential-foo |
| 96 | ------------------------------------------- |
| 97 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 98 | 3. Tell Git to use it. |
Jeff King | a6fc9fd | 2011-12-10 05:31:38 -0500 | [diff] [blame] | 99 | + |
| 100 | ------------------------------------------- |
| 101 | $ git config --global credential.helper foo |
| 102 | ------------------------------------------- |
| 103 | |
Jeff King | a6fc9fd | 2011-12-10 05:31:38 -0500 | [diff] [blame] | 104 | |
| 105 | CREDENTIAL CONTEXTS |
| 106 | ------------------- |
| 107 | |
| 108 | Git considers each credential to have a context defined by a URL. This context |
| 109 | is used to look up context-specific configuration, and is passed to any |
| 110 | helpers, which may use it as an index into secure storage. |
| 111 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 112 | For instance, imagine we are accessing `https://example.com/foo.git`. When Git |
Jeff King | a6fc9fd | 2011-12-10 05:31:38 -0500 | [diff] [blame] | 113 | looks into a config file to see if a section matches this context, it will |
| 114 | consider the two a match if the context is a more-specific subset of the |
| 115 | pattern in the config file. For example, if you have this in your config file: |
| 116 | |
| 117 | -------------------------------------- |
| 118 | [credential "https://example.com"] |
| 119 | username = foo |
| 120 | -------------------------------------- |
| 121 | |
| 122 | then we will match: both protocols are the same, both hosts are the same, and |
| 123 | the "pattern" URL does not care about the path component at all. However, this |
| 124 | context would not match: |
| 125 | |
| 126 | -------------------------------------- |
| 127 | [credential "https://kernel.org"] |
| 128 | username = foo |
| 129 | -------------------------------------- |
| 130 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 131 | because the hostnames differ. Nor would it match `foo.example.com`; Git |
Jeff King | a6fc9fd | 2011-12-10 05:31:38 -0500 | [diff] [blame] | 132 | compares hostnames exactly, without considering whether two hosts are part of |
| 133 | the same domain. Likewise, a config entry for `http://example.com` would not |
brian m. carlson | 46fd7b3 | 2020-02-20 02:24:13 +0000 | [diff] [blame] | 134 | match: Git compares the protocols exactly. However, you may use wildcards in |
| 135 | the domain name and other pattern matching techniques as with the `http.<url>.*` |
| 136 | options. |
Jeff King | a6fc9fd | 2011-12-10 05:31:38 -0500 | [diff] [blame] | 137 | |
David Zych | 4ba3c9b | 2018-09-26 22:23:11 +0000 | [diff] [blame] | 138 | If the "pattern" URL does include a path component, then this too must match |
| 139 | exactly: the context `https://example.com/bar/baz.git` will match a config |
| 140 | entry for `https://example.com/bar/baz.git` (in addition to matching the config |
| 141 | entry for `https://example.com`) but will not match a config entry for |
| 142 | `https://example.com/bar`. |
| 143 | |
Jeff King | a6fc9fd | 2011-12-10 05:31:38 -0500 | [diff] [blame] | 144 | |
| 145 | CONFIGURATION OPTIONS |
| 146 | --------------------- |
| 147 | |
| 148 | Options for a credential context can be configured either in |
Jeff King | 6cf378f | 2012-04-26 04:51:57 -0400 | [diff] [blame] | 149 | `credential.*` (which applies to all credentials), or |
| 150 | `credential.<url>.*`, where <url> matches the context as described |
Jeff King | a6fc9fd | 2011-12-10 05:31:38 -0500 | [diff] [blame] | 151 | above. |
| 152 | |
| 153 | The following options are available in either location: |
| 154 | |
| 155 | helper:: |
| 156 | |
| 157 | The name of an external credential helper, and any associated options. |
| 158 | If the helper name is not an absolute path, then the string `git |
| 159 | credential-` is prepended. The resulting string is executed by the |
| 160 | shell (so, for example, setting this to `foo --option=bar` will execute |
| 161 | `git credential-foo --option=bar` via the shell. See the manual of |
| 162 | specific helpers for examples of their use. |
Jonathan Nieder | 515360f | 2017-05-01 17:21:14 -0700 | [diff] [blame] | 163 | + |
| 164 | If there are multiple instances of the `credential.helper` configuration |
| 165 | variable, each helper will be tried in turn, and may provide a username, |
| 166 | password, or nothing. Once Git has acquired both a username and a |
| 167 | password, no more helpers will be tried. |
| 168 | + |
| 169 | If `credential.helper` is configured to the empty string, this resets |
| 170 | the helper list to empty (so you may override a helper set by a |
| 171 | lower-priority config file by configuring the empty-string helper, |
| 172 | followed by whatever set of helpers you would like). |
Jeff King | a6fc9fd | 2011-12-10 05:31:38 -0500 | [diff] [blame] | 173 | |
| 174 | username:: |
| 175 | |
| 176 | A default username, if one is not provided in the URL. |
| 177 | |
| 178 | useHttpPath:: |
| 179 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 180 | By default, Git does not consider the "path" component of an http URL |
Jeff King | a6fc9fd | 2011-12-10 05:31:38 -0500 | [diff] [blame] | 181 | to be worth matching via external helpers. This means that a credential |
| 182 | stored for `https://example.com/foo.git` will also be used for |
| 183 | `https://example.com/bar.git`. If you do want to distinguish these |
| 184 | cases, set this option to `true`. |
| 185 | |
| 186 | |
| 187 | CUSTOM HELPERS |
| 188 | -------------- |
| 189 | |
| 190 | You can write your own custom helpers to interface with any system in |
Jeff King | cc4f2eb | 2020-02-14 13:54:59 -0500 | [diff] [blame] | 191 | which you keep credentials. |
| 192 | |
| 193 | Credential helpers are programs executed by Git to fetch or save |
| 194 | credentials from and to long-term storage (where "long-term" is simply |
| 195 | longer than a single Git process; e.g., credentials may be stored |
| 196 | in-memory for a few minutes, or indefinitely on disk). |
| 197 | |
| 198 | Each helper is specified by a single string in the configuration |
| 199 | variable `credential.helper` (and others, see linkgit:git-config[1]). |
| 200 | The string is transformed by Git into a command to be executed using |
| 201 | these rules: |
| 202 | |
| 203 | 1. If the helper string begins with "!", it is considered a shell |
| 204 | snippet, and everything after the "!" becomes the command. |
| 205 | |
| 206 | 2. Otherwise, if the helper string begins with an absolute path, the |
| 207 | verbatim helper string becomes the command. |
| 208 | |
| 209 | 3. Otherwise, the string "git credential-" is prepended to the helper |
| 210 | string, and the result becomes the command. |
| 211 | |
| 212 | The resulting command then has an "operation" argument appended to it |
| 213 | (see below for details), and the result is executed by the shell. |
| 214 | |
| 215 | Here are some example specifications: |
| 216 | |
| 217 | ---------------------------------------------------- |
| 218 | # run "git credential-foo" |
| 219 | foo |
| 220 | |
| 221 | # same as above, but pass an argument to the helper |
| 222 | foo --bar=baz |
| 223 | |
| 224 | # the arguments are parsed by the shell, so use shell |
| 225 | # quoting if necessary |
| 226 | foo --bar="whitespace arg" |
| 227 | |
| 228 | # you can also use an absolute path, which will not use the git wrapper |
| 229 | /path/to/my/helper --with-arguments |
| 230 | |
| 231 | # or you can specify your own shell snippet |
| 232 | !f() { echo "password=`cat $HOME/.secret`"; }; f |
| 233 | ---------------------------------------------------- |
| 234 | |
| 235 | Generally speaking, rule (3) above is the simplest for users to specify. |
| 236 | Authors of credential helpers should make an effort to assist their |
| 237 | users by naming their program "git-credential-$NAME", and putting it in |
| 238 | the `$PATH` or `$GIT_EXEC_PATH` during installation, which will allow a |
| 239 | user to enable it with `git config credential.helper $NAME`. |
| 240 | |
| 241 | When a helper is executed, it will have one "operation" argument |
| 242 | appended to its command line, which is one of: |
| 243 | |
| 244 | `get`:: |
| 245 | |
| 246 | Return a matching credential, if any exists. |
| 247 | |
| 248 | `store`:: |
| 249 | |
| 250 | Store the credential, if applicable to the helper. |
| 251 | |
| 252 | `erase`:: |
| 253 | |
| 254 | Remove a matching credential, if any, from the helper's storage. |
| 255 | |
| 256 | The details of the credential will be provided on the helper's stdin |
| 257 | stream. The exact format is the same as the input/output format of the |
| 258 | `git credential` plumbing command (see the section `INPUT/OUTPUT |
| 259 | FORMAT` in linkgit:git-credential[1] for a detailed specification). |
| 260 | |
| 261 | For a `get` operation, the helper should produce a list of attributes on |
| 262 | stdout in the same format (see linkgit:git-credential[1] for common |
| 263 | attributes). A helper is free to produce a subset, or even no values at |
| 264 | all if it has nothing useful to provide. Any provided attributes will |
| 265 | overwrite those already known about by Git. If a helper outputs a |
| 266 | `quit` attribute with a value of `true` or `1`, no further helpers will |
| 267 | be consulted, nor will the user be prompted (if no credential has been |
| 268 | provided, the operation will then fail). |
| 269 | |
| 270 | For a `store` or `erase` operation, the helper's output is ignored. |
| 271 | If it fails to perform the requested operation, it may complain to |
| 272 | stderr to inform the user. If it does not support the requested |
| 273 | operation (e.g., a read-only store), it should silently ignore the |
| 274 | request. |
| 275 | |
| 276 | If a helper receives any other operation, it should silently ignore the |
| 277 | request. This leaves room for future operations to be added (older |
| 278 | helpers will just ignore the new requests). |
Jeff King | a6fc9fd | 2011-12-10 05:31:38 -0500 | [diff] [blame] | 279 | |
| 280 | GIT |
| 281 | --- |
| 282 | Part of the linkgit:git[1] suite |