1GITCREDENTIALS(7)                 Git Manual                 GITCREDENTIALS(7)
2
3
4

NAME

6       gitcredentials - Providing usernames and passwords to Git
7

SYNOPSIS

9       git config credential.https://example.com.username myusername
10       git config credential.helper "$helper $options"
11

DESCRIPTION

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. This manual describes
16       the mechanisms Git uses to request these credentials, as well as some
17       features to avoid inputting these credentials repeatedly.
18

REQUESTING CREDENTIALS

20       Without any credential helpers defined, Git will try the following
21       strategies to ask the user for usernames and passwords:
22
23        1. If the GIT_ASKPASS environment variable is set, the program
24           specified by the variable is invoked. A suitable prompt is provided
25           to the program on the command line, and the user’s input is read
26           from its standard output.
27
28        2. Otherwise, if the core.askPass configuration variable is set, its
29           value is used as above.
30
31        3. Otherwise, if the SSH_ASKPASS environment variable is set, its
32           value is used as above.
33
34        4. Otherwise, the user is prompted on the terminal.
35

AVOIDING REPETITION

37       It can be cumbersome to input the same credentials over and over. Git
38       provides two methods to reduce this annoyance:
39
40        1. Static configuration of usernames for a given authentication
41           context.
42
43        2. Credential helpers to cache or store passwords, or to interact with
44           a system password wallet or keychain.
45
46       The first is simple and appropriate if you do not have secure storage
47       available for a password. It is generally configured by adding this to
48       your config:
49
50           [credential "https://example.com"]
51                   username = me
52
53       Credential helpers, on the other hand, are external programs from which
54       Git can request both usernames and passwords; they typically interface
55       with secure storage provided by the OS or other programs.
56
57       To use a helper, you must first select one to use. Git currently
58       includes the following helpers:
59
60       cache
61           Cache credentials in memory for a short period of time. See git-
62           credential-cache(1) for details.
63
64       store
65           Store credentials indefinitely on disk. See git-credential-store(1)
66           for details.
67
68       You may also have third-party helpers installed; search for
69       credential-* in the output of git help -a, and consult the
70       documentation of individual helpers. Once you have selected a helper,
71       you can tell Git to use it by putting its name into the
72       credential.helper variable.
73
74        1. Find a helper.
75
76               $ git help -a | grep credential-
77               credential-foo
78
79        2. Read its description.
80
81               $ git help credential-foo
82
83        3. Tell Git to use it.
84
85               $ git config --global credential.helper foo
86

CREDENTIAL CONTEXTS

88       Git considers each credential to have a context defined by a URL. This
89       context is used to look up context-specific configuration, and is
90       passed to any helpers, which may use it as an index into secure
91       storage.
92
93       For instance, imagine we are accessing https://example.com/foo.git.
94       When Git looks into a config file to see if a section matches this
95       context, it will consider the two a match if the context is a
96       more-specific subset of the pattern in the config file. For example, if
97       you have this in your config file:
98
99           [credential "https://example.com"]
100                   username = foo
101
102       then we will match: both protocols are the same, both hosts are the
103       same, and the "pattern" URL does not care about the path component at
104       all. However, this context would not match:
105
106           [credential "https://kernel.org"]
107                   username = foo
108
109       because the hostnames differ. Nor would it match foo.example.com; Git
110       compares hostnames exactly, without considering whether two hosts are
111       part of the same domain. Likewise, a config entry for
112       http://example.com would not match: Git compares the protocols exactly.
113       However, you may use wildcards in the domain name and other pattern
114       matching techniques as with the http.<url>.* options.
115
116       If the "pattern" URL does include a path component, then this too must
117       match exactly: the context https://example.com/bar/baz.git will match a
118       config entry for https://example.com/bar/baz.git (in addition to
119       matching the config entry for https://example.com) but will not match a
120       config entry for https://example.com/bar.
121

CONFIGURATION OPTIONS

123       Options for a credential context can be configured either in
124       credential.* (which applies to all credentials), or credential.<url>.*,
125       where <url> matches the context as described above.
126
127       The following options are available in either location:
128
129       helper
130           The name of an external credential helper, and any associated
131           options. If the helper name is not an absolute path, then the
132           string git credential- is prepended. The resulting string is
133           executed by the shell (so, for example, setting this to foo
134           --option=bar will execute git credential-foo --option=bar via the
135           shell. See the manual of specific helpers for examples of their
136           use.
137
138           If there are multiple instances of the credential.helper
139           configuration variable, each helper will be tried in turn, and may
140           provide a username, password, or nothing. Once Git has acquired
141           both a username and a password, no more helpers will be tried.
142
143           If credential.helper is configured to the empty string, this resets
144           the helper list to empty (so you may override a helper set by a
145           lower-priority config file by configuring the empty-string helper,
146           followed by whatever set of helpers you would like).
147
148       username
149           A default username, if one is not provided in the URL.
150
151       useHttpPath
152           By default, Git does not consider the "path" component of an http
153           URL to be worth matching via external helpers. This means that a
154           credential stored for https://example.com/foo.git will also be used
155           for https://example.com/bar.git. If you do want to distinguish
156           these cases, set this option to true.
157

CUSTOM HELPERS

159       You can write your own custom helpers to interface with any system in
160       which you keep credentials.
161
162       Credential helpers are programs executed by Git to fetch or save
163       credentials from and to long-term storage (where "long-term" is simply
164       longer than a single Git process; e.g., credentials may be stored
165       in-memory for a few minutes, or indefinitely on disk).
166
167       Each helper is specified by a single string in the configuration
168       variable credential.helper (and others, see git-config(1)). The string
169       is transformed by Git into a command to be executed using these rules:
170
171        1. If the helper string begins with "!", it is considered a shell
172           snippet, and everything after the "!" becomes the command.
173
174        2. Otherwise, if the helper string begins with an absolute path, the
175           verbatim helper string becomes the command.
176
177        3. Otherwise, the string "git credential-" is prepended to the helper
178           string, and the result becomes the command.
179
180       The resulting command then has an "operation" argument appended to it
181       (see below for details), and the result is executed by the shell.
182
183       Here are some example specifications:
184
185           # run "git credential-foo"
186           [credential]
187                   helper = foo
188
189           # same as above, but pass an argument to the helper
190           [credential]
191                   helper = "foo --bar=baz"
192
193           # the arguments are parsed by the shell, so use shell
194           # quoting if necessary
195           [credential]
196                   helper = "foo --bar='whitespace arg'"
197
198           # you can also use an absolute path, which will not use the git wrapper
199           [credential]
200                   helper = "/path/to/my/helper --with-arguments"
201
202           # or you can specify your own shell snippet
203           [credential "https://example.com"]
204                   username = your_user
205                   helper = "!f() { test \"$1\" = get && echo \"password=$(cat $HOME/.secret)\"; }; f"
206
207       Generally speaking, rule (3) above is the simplest for users to
208       specify. Authors of credential helpers should make an effort to assist
209       their users by naming their program "git-credential-$NAME", and putting
210       it in the $PATH or $GIT_EXEC_PATH during installation, which will allow
211       a user to enable it with git config credential.helper $NAME.
212
213       When a helper is executed, it will have one "operation" argument
214       appended to its command line, which is one of:
215
216       get
217           Return a matching credential, if any exists.
218
219       store
220           Store the credential, if applicable to the helper.
221
222       erase
223           Remove a matching credential, if any, from the helper’s storage.
224
225       The details of the credential will be provided on the helper’s stdin
226       stream. The exact format is the same as the input/output format of the
227       git credential plumbing command (see the section INPUT/OUTPUT FORMAT in
228       git-credential(1) for a detailed specification).
229
230       For a get operation, the helper should produce a list of attributes on
231       stdout in the same format (see git-credential(1) for common
232       attributes). A helper is free to produce a subset, or even no values at
233       all if it has nothing useful to provide. Any provided attributes will
234       overwrite those already known about by Git’s credential subsystem.
235
236       While it is possible to override all attributes, well behaving helpers
237       should refrain from doing so for any attribute other than username and
238       password.
239
240       If a helper outputs a quit attribute with a value of true or 1, no
241       further helpers will be consulted, nor will the user be prompted (if no
242       credential has been provided, the operation will then fail).
243
244       Similarly, no more helpers will be consulted once both username and
245       password had been provided.
246
247       For a store or erase operation, the helper’s output is ignored.
248
249       If a helper fails to perform the requested operation or needs to notify
250       the user of a potential issue, it may write to stderr.
251
252       If it does not support the requested operation (e.g., a read-only
253       store), it should silently ignore the request.
254
255       If a helper receives any other operation, it should silently ignore the
256       request. This leaves room for future operations to be added (older
257       helpers will just ignore the new requests).
258

GIT

260       Part of the git(1) suite
261
262
263
264Git 2.30.2                        2021-03-08                 GITCREDENTIALS(7)
Impressum