]> git.ipfire.org Git - thirdparty/git.git/blame - Documentation/git-credential.txt
Merge branch 'sp/test-i18ngrep' into maint-2.43
[thirdparty/git.git] / Documentation / git-credential.txt
CommitLineData
e30b2feb
JRI
1git-credential(1)
2=================
3
4NAME
5----
fa0aad4f 6git-credential - Retrieve and store user credentials
e30b2feb
JRI
7
8SYNOPSIS
9--------
10------------------
b7bf32b0 11'git credential' (fill|approve|reject)
e30b2feb
JRI
12------------------
13
14DESCRIPTION
15-----------
16
17Git has an internal interface for storing and retrieving credentials
18from system-specific helpers, as well as prompting the user for
19usernames and passwords. The git-credential command exposes this
20interface to scripts which may want to retrieve, store, or prompt for
2de9b711 21credentials in the same manner as Git. The design of this scriptable
f3b90556 22interface models the internal C API; see credential.h for more
e30b2feb
JRI
23background on the concepts.
24
25git-credential takes an "action" option on the command-line (one of
26`fill`, `approve`, or `reject`) and reads a credential description
27on stdin (see <<IOFMT,INPUT/OUTPUT FORMAT>>).
28
29If the action is `fill`, git-credential will attempt to add "username"
30and "password" attributes to the description by reading config files,
31by contacting any configured credential helpers, or by prompting the
32user. The username and password attributes of the credential
33description are then printed to stdout together with the attributes
34already provided.
35
36If the action is `approve`, git-credential will send the description
37to any configured credential helpers, which may store the credential
38for later use.
39
40If the action is `reject`, git-credential will send the description to
41any configured credential helpers, which may erase any stored
6c26da84 42credentials matching the description.
e30b2feb
JRI
43
44If the action is `approve` or `reject`, no output should be emitted.
45
46TYPICAL USE OF GIT CREDENTIAL
47-----------------------------
48
49An application using git-credential will typically use `git
50credential` following these steps:
51
52 1. Generate a credential description based on the context.
53+
54For example, if we want a password for
55`https://example.com/foo.git`, we might generate the following
56credential description (don't forget the blank line at the end; it
57tells `git credential` that the application finished feeding all the
e1c3bf49 58information it has):
e30b2feb
JRI
59
60 protocol=https
61 host=example.com
62 path=foo.git
63
64 2. Ask git-credential to give us a username and password for this
65 description. This is done by running `git credential fill`,
2d6dc182
MM
66 feeding the description from step (1) to its standard input. The complete
67 credential description (including the credential per se, i.e. the
68 login and password) will be produced on standard output, like:
e30b2feb 69
2d6dc182
MM
70 protocol=https
71 host=example.com
e30b2feb
JRI
72 username=bob
73 password=secr3t
74+
2d6dc182 75In most cases, this means the attributes given in the input will be
2de9b711 76repeated in the output, but Git may also modify the credential
2d6dc182
MM
77description, for example by removing the `path` attribute when the
78protocol is HTTP(s) and `credential.useHttpPath` is false.
79+
e30b2feb
JRI
80If the `git credential` knew about the password, this step may
81not have involved the user actually typing this password (the
82user may have typed a password to unlock the keychain instead,
83or no user interaction was done if the keychain was already
84unlocked) before it returned `password=secr3t`.
85
86 3. Use the credential (e.g., access the URL with the username and
87 password from step (2)), and see if it's accepted.
88
89 4. Report on the success or failure of the password. If the
90 credential allowed the operation to complete successfully, then
91 it can be marked with an "approve" action to tell `git
92 credential` to reuse it in its next invocation. If the credential
93 was rejected during the operation, use the "reject" action so
94 that `git credential` will ask for a new password in its next
95 invocation. In either case, `git credential` should be fed with
2d6dc182 96 the credential description obtained from step (2) (which also
cf6cac20 97 contains the fields provided in step (1)).
e30b2feb
JRI
98
99[[IOFMT]]
100INPUT/OUTPUT FORMAT
101-------------------
102
103`git credential` reads and/or writes (depending on the action used)
3e5f29e8 104credential information in its standard input/output. This information
e30b2feb 105can correspond either to keys for which `git credential` will obtain
1aed817f
CMAB
106the login information (e.g. host, protocol, path), or to the actual
107credential data to be obtained (username/password).
e30b2feb 108
3e5f29e8 109The credential is split into a set of named attributes, with one
1aed817f
CMAB
110attribute per line. Each attribute is specified by a key-value pair,
111separated by an `=` (equals) sign, followed by a newline.
112
113The key may contain any bytes except `=`, newline, or NUL. The value may
114contain any bytes except newline or NUL.
115
5f2117b2
MJC
116Attributes with keys that end with C-style array brackets `[]` can have
117multiple values. Each instance of a multi-valued attribute forms an
118ordered list of values - the order of the repeated attributes defines
119the order of the values. An empty multi-valued attribute (`key[]=\n`)
120acts to clear any previous entries and reset the list.
121
122In all cases, all bytes are treated as-is (i.e., there is no quoting,
e30b2feb
JRI
123and one cannot transmit a value with newline or NUL in it). The list of
124attributes is terminated by a blank line or end-of-file.
1aed817f 125
3e5f29e8 126Git understands the following attributes:
e30b2feb
JRI
127
128`protocol`::
129
130 The protocol over which the credential will be used (e.g.,
131 `https`).
132
133`host`::
134
1aed817f
CMAB
135 The remote hostname for a network credential. This includes
136 the port number if one was specified (e.g., "example.com:8088").
e30b2feb
JRI
137
138`path`::
139
140 The path with which the credential will be used. E.g., for
141 accessing a remote https repository, this will be the
142 repository's path on the server.
143
144`username`::
145
146 The credential's username, if we already have one (e.g., from a
1aed817f 147 URL, the configuration, the user, or from a previously run helper).
e30b2feb
JRI
148
149`password`::
150
151 The credential's password, if we are asking it to be stored.
9c183a70 152
d208bfdf
H
153`password_expiry_utc`::
154
155 Generated passwords such as an OAuth access token may have an expiry date.
156 When reading credentials from helpers, `git credential fill` ignores expired
157 passwords. Represented as Unix time UTC, seconds since 1970.
158
a5c76569
H
159`oauth_refresh_token`::
160
161 An OAuth refresh token may accompany a password that is an OAuth access
162 token. Helpers must treat this attribute as confidential like the password
163 attribute. Git itself has no special behaviour for this attribute.
164
9c183a70
JK
165`url`::
166
167 When this special attribute is read by `git credential`, the
168 value is parsed as a URL and treated as if its constituent parts
169 were read (e.g., `url=https://example.com` would behave as if
170 `protocol=https` and `host=example.com` had been provided). This
1aed817f 171 can help callers avoid parsing URLs themselves.
0d9cdbc5
172+
173Note that specifying a protocol is mandatory and if the URL
174doesn't specify a hostname (e.g., "cert:///path/to/file") the
175credential will contain a hostname attribute whose value is an
176empty string.
177+
178Components which are missing from the URL (e.g., there is no
179username in the example above) will be left unset.
cafd9828 180
5f2117b2
MJC
181`wwwauth[]`::
182
183 When an HTTP response is received by Git that includes one or more
184 'WWW-Authenticate' authentication headers, these will be passed by Git
185 to credential helpers.
186+
187Each 'WWW-Authenticate' header value is passed as a multi-valued
188attribute 'wwwauth[]', where the order of the attributes is the same as
189they appear in the HTTP response. This attribute is 'one-way' from Git
190to pass additional information to credential helpers.
191
7fd54b62
H
192Unrecognised attributes are silently discarded.
193
cafd9828
ÆAB
194GIT
195---
196Part of the linkgit:git[1] suite