1GITCREDENTIALS(7) Git Manual GITCREDENTIALS(7)
2
6 gitcredentials - Providing usernames and passwords to Git
7
9 git config credential.https://example.com.username myusername
10 git config credential.helper "$helper $options"
11
13 Git will sometimes need credentials from the user in order to perform
14 operations; for example, it may need to ask for a username and password
15 in order to access a remote repository over HTTP. Some remotes accept a
16 personal access token or OAuth access token as a password. This manual
17 describes the mechanisms Git uses to request these credentials, as well
18 as some features to avoid inputting these credentials repeatedly.
19
21 Without any credential helpers defined, Git will try the following
22 strategies to ask the user for usernames and passwords:
23 1. If the GIT_ASKPASS environment variable is set, the program
25 specified by the variable is invoked. A suitable prompt is provided
26 to the program on the command line, and the user’s input is read
27 from its standard output.
28 2. Otherwise, if the core.askPass configuration variable is set, its
30 value is used as above.
31 3. Otherwise, if the SSH_ASKPASS environment variable is set, its
33 value is used as above.
34 4. Otherwise, the user is prompted on the terminal.
36
38 It can be cumbersome to input the same credentials over and over. Git
39 provides two methods to reduce this annoyance:
40 1. Static configuration of usernames for a given authentication
42 context.
43 2. Credential helpers to cache or store passwords, or to interact with
45 a system password wallet or keychain.
46 The first is simple and appropriate if you do not have secure storage
48 available for a password. It is generally configured by adding this to
49 your config:
50 [credential "https://example.com"]
52 username = me
53 Credential helpers, on the other hand, are external programs from which
55 Git can request both usernames and passwords; they typically interface
56 with secure storage provided by the OS or other programs.
57 Alternatively, a credential-generating helper might generate
58 credentials for certain servers via some API.
59 To use a helper, you must first select one to use. Git currently
61 includes the following helpers:
62 cache
64 Cache credentials in memory for a short period of time. See git-
65 credential-cache(1) for details.
66 store
68 Store credentials indefinitely on disk. See git-credential-store(1)
69 for details.
70 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 1. Find a helper.
78 $ git help -a | grep credential-
80 credential-foo
81 2. Read its description.
83 $ git help credential-foo
85 3. Tell Git to use it.
87 $ git config --global credential.helper foo
89 Available helpers
91 The community maintains a comprehensive list of Git credential helpers
92 at https://git-scm.com/doc/credential-helpers.
93 OAuth
95 An alternative to inputting passwords or personal access tokens is to
96 use an OAuth credential helper. Initial authentication opens a browser
97 window to the host. Subsequent authentication happens in the
98 background. Many popular Git hosts support OAuth.
99
101 Git considers each credential to have a context defined by a URL. This
102 context is used to look up context-specific configuration, and is
103 passed to any helpers, which may use it as an index into secure
104 storage.
105 For instance, imagine we are accessing https://example.com/foo.git.
107 When Git looks into a config file to see if a section matches this
108 context, it will consider the two a match if the context is a
109 more-specific subset of the pattern in the config file. For example, if
110 you have this in your config file:
111 [credential "https://example.com"]
113 username = foo
114 then we will match: both protocols are the same, both hosts are the
116 same, and the "pattern" URL does not care about the path component at
117 all. However, this context would not match:
118 [credential "https://kernel.org"]
120 username = foo
121 because the hostnames differ. Nor would it match foo.example.com; Git
123 compares hostnames exactly, without considering whether two hosts are
124 part of the same domain. Likewise, a config entry for
125 http://example.com would not match: Git compares the protocols exactly.
126 However, you may use wildcards in the domain name and other pattern
127 matching techniques as with the http.<URL>.* options.
128 If the "pattern" URL does include a path component, then this too must
130 match exactly: the context https://example.com/bar/baz.git will match a
131 config entry for https://example.com/bar/baz.git (in addition to
132 matching the config entry for https://example.com) but will not match a
133 config entry for https://example.com/bar.
134
136 Options for a credential context can be configured either in
137 credential.* (which applies to all credentials), or credential.<URL>.*,
138 where <URL> matches the context as described above.
139 The following options are available in either location:
141 helper
143 The name of an external credential helper, and any associated
144 options. If the helper name is not an absolute path, then the
145 string git credential- is prepended. The resulting string is
146 executed by the shell (so, for example, setting this to foo
147 --option=bar will execute git credential-foo --option=bar via the
148 shell. See the manual of specific helpers for examples of their
149 use.
150 If there are multiple instances of the credential.helper
152 configuration variable, each helper will be tried in turn, and may
153 provide a username, password, or nothing. Once Git has acquired
154 both a username and a non-expired password, no more helpers will be
155 tried.
156 If credential.helper is configured to the empty string, this resets
158 the helper list to empty (so you may override a helper set by a
159 lower-priority config file by configuring the empty-string helper,
160 followed by whatever set of helpers you would like).
161 username
163 A default username, if one is not provided in the URL.
164 useHttpPath
166 By default, Git does not consider the "path" component of an http
167 URL to be worth matching via external helpers. This means that a
168 credential stored for https://example.com/foo.git will also be used
169 for https://example.com/bar.git. If you do want to distinguish
170 these cases, set this option to true.
171
173 You can write your own custom helpers to interface with any system in
174 which you keep credentials.
175 Credential helpers are programs executed by Git to fetch or save
177 credentials from and to long-term storage (where "long-term" is simply
178 longer than a single Git process; e.g., credentials may be stored
179 in-memory for a few minutes, or indefinitely on disk).
180 Each helper is specified by a single string in the configuration
182 variable credential.helper (and others, see git-config(1)). The string
183 is transformed by Git into a command to be executed using these rules:
184 1. If the helper string begins with "!", it is considered a shell
186 snippet, and everything after the "!" becomes the command.
187 2. Otherwise, if the helper string begins with an absolute path, the
189 verbatim helper string becomes the command.
190 3. Otherwise, the string "git credential-" is prepended to the helper
192 string, and the result becomes the command.
193 The resulting command then has an "operation" argument appended to it
195 (see below for details), and the result is executed by the shell.
196 Here are some example specifications:
198 # run "git credential-foo"
200 [credential]
201 helper = foo
202 # same as above, but pass an argument to the helper
204 [credential]
205 helper = "foo --bar=baz"
206 # the arguments are parsed by the shell, so use shell
208 # quoting if necessary
209 [credential]
210 helper = "foo --bar='whitespace arg'"
211 # you can also use an absolute path, which will not use the git wrapper
213 [credential]
214 helper = "/path/to/my/helper --with-arguments"
215 # or you can specify your own shell snippet
217 [credential "https://example.com"]
218 username = your_user
219 helper = "!f() { test \"$1\" = get && echo \"password=$(cat $HOME/.secret)\"; }; f"
220 Generally speaking, rule (3) above is the simplest for users to
222 specify. Authors of credential helpers should make an effort to assist
223 their users by naming their program "git-credential-$NAME", and putting
224 it in the $PATH or $GIT_EXEC_PATH during installation, which will allow
225 a user to enable it with git config credential.helper $NAME.
226 When a helper is executed, it will have one "operation" argument
228 appended to its command line, which is one of:
229 get
231 Return a matching credential, if any exists.
232 store
234 Store the credential, if applicable to the helper.
235 erase
237 Remove matching credentials, if any, from the helper’s storage.
238 The details of the credential will be provided on the helper’s stdin
240 stream. The exact format is the same as the input/output format of the
241 git credential plumbing command (see the section INPUT/OUTPUT FORMAT in
242 git-credential(1) for a detailed specification).
243 For a get operation, the helper should produce a list of attributes on
245 stdout in the same format (see git-credential(1) for common
246 attributes). A helper is free to produce a subset, or even no values at
247 all if it has nothing useful to provide. Any provided attributes will
248 overwrite those already known about by Git’s credential subsystem.
249 Unrecognised attributes are silently discarded.
250 While it is possible to override all attributes, well behaving helpers
252 should refrain from doing so for any attribute other than username and
253 password.
254 If a helper outputs a quit attribute with a value of true or 1, no
256 further helpers will be consulted, nor will the user be prompted (if no
257 credential has been provided, the operation will then fail).
258 Similarly, no more helpers will be consulted once both username and
260 password had been provided.
261 For a store or erase operation, the helper’s output is ignored.
263 If a helper fails to perform the requested operation or needs to notify
265 the user of a potential issue, it may write to stderr.
266 If it does not support the requested operation (e.g., a read-only store
268 or generator), it should silently ignore the request.
269 If a helper receives any other operation, it should silently ignore the
271 request. This leaves room for future operations to be added (older
272 helpers will just ignore the new requests).
273
275 Part of the git(1) suite
276Git 2.43.0 11/20/2023 GITCREDENTIALS(7)