]>
Commit | Line | Data |
---|---|---|
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. This manual describes | |
21 | the mechanisms Git uses to request these credentials, as well as some | |
22 | features to avoid inputting these credentials repeatedly. | |
23 | ||
24 | REQUESTING CREDENTIALS | |
25 | ---------------------- | |
26 | ||
27 | Without any credential helpers defined, Git will try the following | |
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 | ||
35 | 2. Otherwise, if the `core.askpass` configuration variable is set, its | |
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 | ||
62 | Credential helpers, on the other hand, are external programs from which Git can | |
63 | request both usernames and passwords; they typically interface with secure | |
64 | storage provided by the OS or other programs. | |
65 | ||
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 | ||
74 | store:: | |
75 | ||
76 | Store credentials indefinitely on disk. See | |
77 | linkgit:git-credential-store[1] for details. | |
78 | ||
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, | |
82 | you can tell Git to use it by putting its name into the | |
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 | ||
98 | 3. Tell Git to use it. | |
99 | + | |
100 | ------------------------------------------- | |
101 | $ git config --global credential.helper foo | |
102 | ------------------------------------------- | |
103 | ||
104 | If there are multiple instances of the `credential.helper` configuration | |
105 | variable, each helper will be tried in turn, and may provide a username, | |
106 | password, or nothing. Once Git has acquired both a username and a | |
107 | password, no more helpers will be tried. | |
108 | ||
109 | ||
110 | CREDENTIAL CONTEXTS | |
111 | ------------------- | |
112 | ||
113 | Git considers each credential to have a context defined by a URL. This context | |
114 | is used to look up context-specific configuration, and is passed to any | |
115 | helpers, which may use it as an index into secure storage. | |
116 | ||
117 | For instance, imagine we are accessing `https://example.com/foo.git`. When Git | |
118 | looks into a config file to see if a section matches this context, it will | |
119 | consider the two a match if the context is a more-specific subset of the | |
120 | pattern in the config file. For example, if you have this in your config file: | |
121 | ||
122 | -------------------------------------- | |
123 | [credential "https://example.com"] | |
124 | username = foo | |
125 | -------------------------------------- | |
126 | ||
127 | then we will match: both protocols are the same, both hosts are the same, and | |
128 | the "pattern" URL does not care about the path component at all. However, this | |
129 | context would not match: | |
130 | ||
131 | -------------------------------------- | |
132 | [credential "https://kernel.org"] | |
133 | username = foo | |
134 | -------------------------------------- | |
135 | ||
136 | because the hostnames differ. Nor would it match `foo.example.com`; Git | |
137 | compares hostnames exactly, without considering whether two hosts are part of | |
138 | the same domain. Likewise, a config entry for `http://example.com` would not | |
139 | match: Git compares the protocols exactly. | |
140 | ||
141 | ||
142 | CONFIGURATION OPTIONS | |
143 | --------------------- | |
144 | ||
145 | Options for a credential context can be configured either in | |
146 | `credential.*` (which applies to all credentials), or | |
147 | `credential.<url>.*`, where <url> matches the context as described | |
148 | above. | |
149 | ||
150 | The following options are available in either location: | |
151 | ||
152 | helper:: | |
153 | ||
154 | The name of an external credential helper, and any associated options. | |
155 | If the helper name is not an absolute path, then the string `git | |
156 | credential-` is prepended. The resulting string is executed by the | |
157 | shell (so, for example, setting this to `foo --option=bar` will execute | |
158 | `git credential-foo --option=bar` via the shell. See the manual of | |
159 | specific helpers for examples of their use. | |
160 | ||
161 | username:: | |
162 | ||
163 | A default username, if one is not provided in the URL. | |
164 | ||
165 | useHttpPath:: | |
166 | ||
167 | By default, Git does not consider the "path" component of an http URL | |
168 | to be worth matching via external helpers. This means that a credential | |
169 | stored for `https://example.com/foo.git` will also be used for | |
170 | `https://example.com/bar.git`. If you do want to distinguish these | |
171 | cases, set this option to `true`. | |
172 | ||
173 | ||
174 | CUSTOM HELPERS | |
175 | -------------- | |
176 | ||
177 | You can write your own custom helpers to interface with any system in | |
178 | which you keep credentials. See the documentation for Git's | |
179 | link:technical/api-credentials.html[credentials API] for details. | |
180 | ||
181 | GIT | |
182 | --- | |
183 | Part of the linkgit:git[1] suite |