freshlybakedca.ke
Git fork
1git-credential(1)
2=================
3
4NAME
5----
6git-credential - Retrieve and store user credentials
7
8SYNOPSIS
9--------
10------------------
11'git credential' (fill|approve|reject|capability)
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
21credentials in the same manner as Git. The design of this scriptable
22interface models the internal C API; see credential.h for more
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
42credentials matching the description.
43
44If the action is `capability`, git-credential will announce any capabilities
45it supports to standard output.
46
47If the action is `approve` or `reject`, no output should be emitted.
48
49TYPICAL USE OF GIT CREDENTIAL
50-----------------------------
51
52An application using git-credential will typically use `git
53credential` following these steps:
54
55 1. Generate a credential description based on the context.
56+
57For example, if we want a password for
58`https://example.com/foo.git`, we might generate the following
59credential description (don't forget the blank line at the end; it
60tells `git credential` that the application finished feeding all the
61information it has):
62
63 protocol=https
64 host=example.com
65 path=foo.git
66
67 2. Ask git-credential to give us a username and password for this
68 description. This is done by running `git credential fill`,
69 feeding the description from step (1) to its standard input. The complete
70 credential description (including the credential per se, i.e. the
71 login and password) will be produced on standard output, like:
72
73 protocol=https
74 host=example.com
75 username=bob
76 password=secr3t
77+
78In most cases, this means the attributes given in the input will be
79repeated in the output, but Git may also modify the credential
80description, for example by removing the `path` attribute when the
81protocol is HTTP(s) and `credential.useHttpPath` is false.
82+
83If the `git credential` knew about the password, this step may
84not have involved the user actually typing this password (the
85user may have typed a password to unlock the keychain instead,
86or no user interaction was done if the keychain was already
87unlocked) before it returned `password=secr3t`.
88
89 3. Use the credential (e.g., access the URL with the username and
90 password from step (2)), and see if it's accepted.
91
92 4. Report on the success or failure of the password. If the
93 credential allowed the operation to complete successfully, then
94 it can be marked with an "approve" action to tell `git
95 credential` to reuse it in its next invocation. If the credential
96 was rejected during the operation, use the "reject" action so
97 that `git credential` will ask for a new password in its next
98 invocation. In either case, `git credential` should be fed with
99 the credential description obtained from step (2) (which also
100 contains the fields provided in step (1)).
101
102[[IOFMT]]
103INPUT/OUTPUT FORMAT
104-------------------
105
106`git credential` reads and/or writes (depending on the action used)
107credential information in its standard input/output. This information
108can correspond either to keys for which `git credential` will obtain
109the login information (e.g. host, protocol, path), or to the actual
110credential data to be obtained (username/password).
111
112The credential is split into a set of named attributes, with one
113attribute per line. Each attribute is specified by a key-value pair,
114separated by an `=` (equals) sign, followed by a newline.
115
116The key may contain any bytes except `=`, newline, or NUL. The value may
117contain any bytes except newline or NUL. A line, including the trailing
118newline, may not exceed 65535 bytes in order to allow implementations to
119parse efficiently.
120
121Attributes with keys that end with C-style array brackets `[]` can have
122multiple values. Each instance of a multi-valued attribute forms an
123ordered list of values - the order of the repeated attributes defines
124the order of the values. An empty multi-valued attribute (`key[]=\n`)
125acts to clear any previous entries and reset the list.
126
127In all cases, all bytes are treated as-is (i.e., there is no quoting,
128and one cannot transmit a value with newline or NUL in it). The list of
129attributes is terminated by a blank line or end-of-file.
130
131Git understands the following attributes:
132
133`protocol`::
134
135 The protocol over which the credential will be used (e.g.,
136 `https`).
137
138`host`::
139
140 The remote hostname for a network credential. This includes
141 the port number if one was specified (e.g., "example.com:8088").
142
143`path`::
144
145 The path with which the credential will be used. E.g., for
146 accessing a remote https repository, this will be the
147 repository's path on the server.
148
149`username`::
150
151 The credential's username, if we already have one (e.g., from a
152 URL, the configuration, the user, or from a previously run helper).
153
154`password`::
155
156 The credential's password, if we are asking it to be stored.
157
158`password_expiry_utc`::
159
160 Generated passwords such as an OAuth access token may have an expiry date.
161 When reading credentials from helpers, `git credential fill` ignores expired
162 passwords. Represented as Unix time UTC, seconds since 1970.
163
164`oauth_refresh_token`::
165
166 An OAuth refresh token may accompany a password that is an OAuth access
167 token. Helpers must treat this attribute as confidential like the password
168 attribute. Git itself has no special behaviour for this attribute.
169
170`url`::
171
172 When this special attribute is read by `git credential`, the
173 value is parsed as a URL and treated as if its constituent parts
174 were read (e.g., `url=https://example.com` would behave as if
175 `protocol=https` and `host=example.com` had been provided). This
176 can help callers avoid parsing URLs themselves.
177+
178Note that specifying a protocol is mandatory and if the URL
179doesn't specify a hostname (e.g., "cert:///path/to/file") the
180credential will contain a hostname attribute whose value is an
181empty string.
182+
183Components which are missing from the URL (e.g., there is no
184username in the example above) will be left unset.
185
186`authtype`::
187 This indicates that the authentication scheme in question should be used.
188 Common values for HTTP and HTTPS include `basic`, `bearer`, and `digest`,
189 although the latter is insecure and should not be used. If `credential`
190 is used, this may be set to an arbitrary string suitable for the protocol in
191 question (usually HTTP).
192+
193This value should not be sent unless the appropriate capability (see below) is
194provided on input.
195
196`credential`::
197 The pre-encoded credential, suitable for the protocol in question (usually
198 HTTP). If this key is sent, `authtype` is mandatory, and `username` and
199 `password` are not used. For HTTP, Git concatenates the `authtype` value and
200 this value with a single space to determine the `Authorization` header.
201+
202This value should not be sent unless the appropriate capability (see below) is
203provided on input.
204
205`ephemeral`::
206 This boolean value indicates, if true, that the value in the `credential`
207 field should not be saved by the credential helper because its usefulness is
208 limited in time. For example, an HTTP Digest `credential` value is computed
209 using a nonce and reusing it will not result in successful authentication.
210 This may also be used for situations with short duration (e.g., 24-hour)
211 credentials. The default value is false.
212+
213The credential helper will still be invoked with `store` or `erase` so that it
214can determine whether the operation was successful.
215+
216This value should not be sent unless the appropriate capability (see below) is
217provided on input.
218
219`state[]`::
220 This value provides an opaque state that will be passed back to this helper
221 if it is called again. Each different credential helper may specify this
222 once. The value should include a prefix unique to the credential helper and
223 should ignore values that don't match its prefix.
224+
225This value should not be sent unless the appropriate capability (see below) is
226provided on input.
227
228`continue`::
229 This is a boolean value, which, if enabled, indicates that this
230 authentication is a non-final part of a multistage authentication step. This
231 is common in protocols such as NTLM and Kerberos, where two rounds of client
232 authentication are required, and setting this flag allows the credential
233 helper to implement the multistage authentication step. This flag should
234 only be sent if a further stage is required; that is, if another round of
235 authentication is expected.
236+
237This value should not be sent unless the appropriate capability (see below) is
238provided on input. This attribute is 'one-way' from a credential helper to
239pass information to Git (or other programs invoking `git credential`).
240
241`wwwauth[]`::
242
243 When an HTTP response is received by Git that includes one or more
244 'WWW-Authenticate' authentication headers, these will be passed by Git
245 to credential helpers.
246+
247Each 'WWW-Authenticate' header value is passed as a multi-valued
248attribute 'wwwauth[]', where the order of the attributes is the same as
249they appear in the HTTP response. This attribute is 'one-way' from Git
250to pass additional information to credential helpers.
251
252`capability[]`::
253 This signals that Git, or the helper, as appropriate, supports the capability
254 in question. This can be used to provide better, more specific data as part
255 of the protocol. A `capability[]` directive must precede any value depending
256 on it and these directives _should_ be the first item announced in the
257 protocol.
258+
259There are two currently supported capabilities. The first is `authtype`, which
260indicates that the `authtype`, `credential`, and `ephemeral` values are
261understood. The second is `state`, which indicates that the `state[]` and
262`continue` values are understood.
263+
264It is not obligatory to use the additional features just because the capability
265is supported, but they should not be provided without the capability.
266
267Unrecognised attributes and capabilities are silently discarded.
268
269[[CAPA-IOFMT]]
270CAPABILITY INPUT/OUTPUT FORMAT
271------------------------------
272
273For `git credential capability`, the format is slightly different. First, a
274`version 0` announcement is made to indicate the current version of the
275protocol, and then each capability is announced with a line like `capability
276authtype`. Credential helpers may also implement this format, again with the
277`capability` argument. Additional lines may be added in the future; callers
278should ignore lines which they don't understand.
279
280Because this is a new part of the credential helper protocol, older versions of
281Git, as well as some credential helpers, may not support it. If a non-zero
282exit status is received, or if the first line doesn't start with the word
283`version` and a space, callers should assume that no capabilities are supported.
284
285The intention of this format is to differentiate it from the credential output
286in an unambiguous way. It is possible to use very simple credential helpers
287(e.g., inline shell scripts) which always produce identical output. Using a
288distinct format allows users to continue to use this syntax without having to
289worry about correctly implementing capability advertisements or accidentally
290confusing callers querying for capabilities.
291
292GIT
293---
294Part of the linkgit:git[1] suite