]>
Commit | Line | Data |
---|---|---|
a6fc9fd3 JK |
1 | gitcredentials(7) |
2 | ================= | |
3 | ||
4 | NAME | |
5 | ---- | |
2135e1ad | 6 | gitcredentials - Providing usernames and passwords to Git |
a6fc9fd3 JK |
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 | |
54e95b46 H |
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. | |
a6fc9fd3 JK |
24 | |
25 | REQUESTING CREDENTIALS | |
26 | ---------------------- | |
27 | ||
2de9b711 | 28 | Without any credential helpers defined, Git will try the following |
a6fc9fd3 JK |
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 | ||
da0005b8 | 36 | 2. Otherwise, if the `core.askPass` configuration variable is set, its |
a6fc9fd3 JK |
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 | ||
2de9b711 | 63 | Credential helpers, on the other hand, are external programs from which Git can |
a6fc9fd3 | 64 | request both usernames and passwords; they typically interface with secure |
dabb9d87 H |
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. | |
a6fc9fd3 | 68 | |
e2770979 JK |
69 | To use a helper, you must first select one to use. Git currently |
70 | includes the following helpers: | |
71 | ||
72 | cache:: | |
73 | ||
74 | Cache credentials in memory for a short period of time. See | |
75 | linkgit:git-credential-cache[1] for details. | |
76 | ||
71e1b4b6 JK |
77 | store:: |
78 | ||
79 | Store credentials indefinitely on disk. See | |
80 | linkgit:git-credential-store[1] for details. | |
81 | ||
e2770979 JK |
82 | You may also have third-party helpers installed; search for |
83 | `credential-*` in the output of `git help -a`, and consult the | |
84 | documentation of individual helpers. Once you have selected a helper, | |
2de9b711 | 85 | you can tell Git to use it by putting its name into the |
a6fc9fd3 JK |
86 | credential.helper variable. |
87 | ||
88 | 1. Find a helper. | |
89 | + | |
90 | ------------------------------------------- | |
91 | $ git help -a | grep credential- | |
92 | credential-foo | |
93 | ------------------------------------------- | |
94 | ||
95 | 2. Read its description. | |
96 | + | |
97 | ------------------------------------------- | |
98 | $ git help credential-foo | |
99 | ------------------------------------------- | |
100 | ||
2de9b711 | 101 | 3. Tell Git to use it. |
a6fc9fd3 JK |
102 | + |
103 | ------------------------------------------- | |
104 | $ git config --global credential.helper foo | |
105 | ------------------------------------------- | |
106 | ||
4c9cb51f H |
107 | === Available helpers |
108 | ||
109 | The community maintains a comprehensive list of Git credential helpers at | |
110 | https://git-scm.com/doc/credential-helpers. | |
111 | ||
112 | === OAuth | |
113 | ||
114 | An alternative to inputting passwords or personal access tokens is to use an | |
115 | OAuth credential helper. Initial authentication opens a browser window to the | |
116 | host. Subsequent authentication happens in the background. Many popular Git | |
117 | hosts support OAuth. | |
a6fc9fd3 JK |
118 | |
119 | CREDENTIAL CONTEXTS | |
120 | ------------------- | |
121 | ||
122 | Git considers each credential to have a context defined by a URL. This context | |
123 | is used to look up context-specific configuration, and is passed to any | |
124 | helpers, which may use it as an index into secure storage. | |
125 | ||
2de9b711 | 126 | For instance, imagine we are accessing `https://example.com/foo.git`. When Git |
a6fc9fd3 JK |
127 | looks into a config file to see if a section matches this context, it will |
128 | consider the two a match if the context is a more-specific subset of the | |
129 | pattern in the config file. For example, if you have this in your config file: | |
130 | ||
131 | -------------------------------------- | |
132 | [credential "https://example.com"] | |
133 | username = foo | |
134 | -------------------------------------- | |
135 | ||
136 | then we will match: both protocols are the same, both hosts are the same, and | |
137 | the "pattern" URL does not care about the path component at all. However, this | |
138 | context would not match: | |
139 | ||
140 | -------------------------------------- | |
141 | [credential "https://kernel.org"] | |
142 | username = foo | |
143 | -------------------------------------- | |
144 | ||
2de9b711 | 145 | because the hostnames differ. Nor would it match `foo.example.com`; Git |
a6fc9fd3 JK |
146 | compares hostnames exactly, without considering whether two hosts are part of |
147 | the same domain. Likewise, a config entry for `http://example.com` would not | |
46fd7b39 | 148 | match: Git compares the protocols exactly. However, you may use wildcards in |
7706294e | 149 | the domain name and other pattern matching techniques as with the `http.<URL>.*` |
46fd7b39 | 150 | options. |
a6fc9fd3 | 151 | |
4ba3c9be DZ |
152 | If the "pattern" URL does include a path component, then this too must match |
153 | exactly: the context `https://example.com/bar/baz.git` will match a config | |
154 | entry for `https://example.com/bar/baz.git` (in addition to matching the config | |
155 | entry for `https://example.com`) but will not match a config entry for | |
156 | `https://example.com/bar`. | |
157 | ||
a6fc9fd3 JK |
158 | |
159 | CONFIGURATION OPTIONS | |
160 | --------------------- | |
161 | ||
162 | Options for a credential context can be configured either in | |
6cf378f0 | 163 | `credential.*` (which applies to all credentials), or |
7706294e | 164 | `credential.<URL>.*`, where <URL> matches the context as described |
a6fc9fd3 JK |
165 | above. |
166 | ||
167 | The following options are available in either location: | |
168 | ||
169 | helper:: | |
170 | ||
171 | The name of an external credential helper, and any associated options. | |
172 | If the helper name is not an absolute path, then the string `git | |
173 | credential-` is prepended. The resulting string is executed by the | |
174 | shell (so, for example, setting this to `foo --option=bar` will execute | |
175 | `git credential-foo --option=bar` via the shell. See the manual of | |
176 | specific helpers for examples of their use. | |
515360f9 JN |
177 | + |
178 | If there are multiple instances of the `credential.helper` configuration | |
179 | variable, each helper will be tried in turn, and may provide a username, | |
180 | password, or nothing. Once Git has acquired both a username and a | |
d208bfdf | 181 | non-expired password, no more helpers will be tried. |
515360f9 JN |
182 | + |
183 | If `credential.helper` is configured to the empty string, this resets | |
184 | the helper list to empty (so you may override a helper set by a | |
185 | lower-priority config file by configuring the empty-string helper, | |
186 | followed by whatever set of helpers you would like). | |
a6fc9fd3 JK |
187 | |
188 | username:: | |
189 | ||
190 | A default username, if one is not provided in the URL. | |
191 | ||
192 | useHttpPath:: | |
193 | ||
2de9b711 | 194 | By default, Git does not consider the "path" component of an http URL |
a6fc9fd3 JK |
195 | to be worth matching via external helpers. This means that a credential |
196 | stored for `https://example.com/foo.git` will also be used for | |
197 | `https://example.com/bar.git`. If you do want to distinguish these | |
198 | cases, set this option to `true`. | |
199 | ||
200 | ||
201 | CUSTOM HELPERS | |
202 | -------------- | |
203 | ||
204 | You can write your own custom helpers to interface with any system in | |
cc4f2eb8 JK |
205 | which you keep credentials. |
206 | ||
207 | Credential helpers are programs executed by Git to fetch or save | |
208 | credentials from and to long-term storage (where "long-term" is simply | |
209 | longer than a single Git process; e.g., credentials may be stored | |
210 | in-memory for a few minutes, or indefinitely on disk). | |
211 | ||
212 | Each helper is specified by a single string in the configuration | |
213 | variable `credential.helper` (and others, see linkgit:git-config[1]). | |
214 | The string is transformed by Git into a command to be executed using | |
215 | these rules: | |
216 | ||
217 | 1. If the helper string begins with "!", it is considered a shell | |
218 | snippet, and everything after the "!" becomes the command. | |
219 | ||
220 | 2. Otherwise, if the helper string begins with an absolute path, the | |
221 | verbatim helper string becomes the command. | |
222 | ||
223 | 3. Otherwise, the string "git credential-" is prepended to the helper | |
224 | string, and the result becomes the command. | |
225 | ||
226 | The resulting command then has an "operation" argument appended to it | |
227 | (see below for details), and the result is executed by the shell. | |
228 | ||
229 | Here are some example specifications: | |
230 | ||
231 | ---------------------------------------------------- | |
232 | # run "git credential-foo" | |
dbe80f92 JK |
233 | [credential] |
234 | helper = foo | |
cc4f2eb8 JK |
235 | |
236 | # same as above, but pass an argument to the helper | |
dbe80f92 JK |
237 | [credential] |
238 | helper = "foo --bar=baz" | |
cc4f2eb8 JK |
239 | |
240 | # the arguments are parsed by the shell, so use shell | |
241 | # quoting if necessary | |
dbe80f92 JK |
242 | [credential] |
243 | helper = "foo --bar='whitespace arg'" | |
cc4f2eb8 JK |
244 | |
245 | # you can also use an absolute path, which will not use the git wrapper | |
dbe80f92 JK |
246 | [credential] |
247 | helper = "/path/to/my/helper --with-arguments" | |
cc4f2eb8 JK |
248 | |
249 | # or you can specify your own shell snippet | |
177681a0 JK |
250 | [credential "https://example.com"] |
251 | username = your_user | |
252 | helper = "!f() { test \"$1\" = get && echo \"password=$(cat $HOME/.secret)\"; }; f" | |
cc4f2eb8 JK |
253 | ---------------------------------------------------- |
254 | ||
255 | Generally speaking, rule (3) above is the simplest for users to specify. | |
256 | Authors of credential helpers should make an effort to assist their | |
257 | users by naming their program "git-credential-$NAME", and putting it in | |
258 | the `$PATH` or `$GIT_EXEC_PATH` during installation, which will allow a | |
259 | user to enable it with `git config credential.helper $NAME`. | |
260 | ||
261 | When a helper is executed, it will have one "operation" argument | |
262 | appended to its command line, which is one of: | |
263 | ||
264 | `get`:: | |
265 | ||
266 | Return a matching credential, if any exists. | |
267 | ||
268 | `store`:: | |
269 | ||
270 | Store the credential, if applicable to the helper. | |
271 | ||
272 | `erase`:: | |
273 | ||
6c26da84 | 274 | Remove matching credentials, if any, from the helper's storage. |
cc4f2eb8 JK |
275 | |
276 | The details of the credential will be provided on the helper's stdin | |
277 | stream. The exact format is the same as the input/output format of the | |
278 | `git credential` plumbing command (see the section `INPUT/OUTPUT | |
279 | FORMAT` in linkgit:git-credential[1] for a detailed specification). | |
280 | ||
281 | For a `get` operation, the helper should produce a list of attributes on | |
282 | stdout in the same format (see linkgit:git-credential[1] for common | |
283 | attributes). A helper is free to produce a subset, or even no values at | |
284 | all if it has nothing useful to provide. Any provided attributes will | |
4b8938be | 285 | overwrite those already known about by Git's credential subsystem. |
7fd54b62 | 286 | Unrecognised attributes are silently discarded. |
4b8938be CMAB |
287 | |
288 | While it is possible to override all attributes, well behaving helpers | |
289 | should refrain from doing so for any attribute other than username and | |
290 | password. | |
291 | ||
292 | If a helper outputs a `quit` attribute with a value of `true` or `1`, | |
293 | no further helpers will be consulted, nor will the user be prompted | |
294 | (if no credential has been provided, the operation will then fail). | |
295 | ||
296 | Similarly, no more helpers will be consulted once both username and | |
297 | password had been provided. | |
cc4f2eb8 JK |
298 | |
299 | For a `store` or `erase` operation, the helper's output is ignored. | |
4b8938be CMAB |
300 | |
301 | If a helper fails to perform the requested operation or needs to notify | |
302 | the user of a potential issue, it may write to stderr. | |
303 | ||
dabb9d87 H |
304 | If it does not support the requested operation (e.g., a read-only store |
305 | or generator), it should silently ignore the request. | |
cc4f2eb8 JK |
306 | |
307 | If a helper receives any other operation, it should silently ignore the | |
308 | request. This leaves room for future operations to be added (older | |
309 | helpers will just ignore the new requests). | |
a6fc9fd3 JK |
310 | |
311 | GIT | |
312 | --- | |
313 | Part of the linkgit:git[1] suite |