Documentation/git-credential.txt

   1 git-credential(1)
   2 =================
   3
   4 NAME
   5 ----
   6 git-credential - Retrieve and store user credentials
   7
   8 SYNOPSIS
   9 --------
  10 ------------------
  11 'git credential' (fill|approve|reject|capability)
  12 ------------------
  13
  14 DESCRIPTION
  15 -----------
  16
  17 Git has an internal interface for storing and retrieving credentials
  18 from system-specific helpers, as well as prompting the user for
  19 usernames and passwords. The git-credential command exposes this
  20 interface to scripts which may want to retrieve, store, or prompt for
  21 credentials in the same manner as Git. The design of this scriptable
  22 interface models the internal C API; see credential.h for more
  23 background on the concepts.
  24
  25 git-credential takes an "action" option on the command-line (one of
  26 `fill`, `approve`, or `reject`) and reads a credential description
  27 on stdin (see <<IOFMT,INPUT/OUTPUT FORMAT>>).
  28
  29 If the action is `fill`, git-credential will attempt to add "username"
  30 and "password" attributes to the description by reading config files,
  31 by contacting any configured credential helpers, or by prompting the
  32 user. The username and password attributes of the credential
  33 description are then printed to stdout together with the attributes
  34 already provided.
  35
  36 If the action is `approve`, git-credential will send the description
  37 to any configured credential helpers, which may store the credential
  38 for later use.
  39
  40 If the action is `reject`, git-credential will send the description to
  41 any configured credential helpers, which may erase any stored
  42 credentials matching the description.
  43
  44 If the action is `capability`, git-credential will announce any capabilities
  45 it supports to standard output.
  46
  47 If the action is `approve` or `reject`, no output should be emitted.
  48
  49 TYPICAL USE OF GIT CREDENTIAL
  50 -----------------------------
  51
  52 An application using git-credential will typically use `git
  53 credential` following these steps:
  54
  55   1. Generate a credential description based on the context.
  56 +
  57 For example, if we want a password for
  58 `https://example.com/foo.git`, we might generate the following
  59 credential description (don't forget the blank line at the end; it
  60 tells `git credential` that the application finished feeding all the
  61 information 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 +
  78 In most cases, this means the attributes given in the input will be
  79 repeated in the output, but Git may also modify the credential
  80 description, for example by removing the `path` attribute when the
  81 protocol is HTTP(s) and `credential.useHttpPath` is false.
  82 +
  83 If the `git credential` knew about the password, this step may
  84 not have involved the user actually typing this password (the
  85 user may have typed a password to unlock the keychain instead,
  86 or no user interaction was done if the keychain was already
  87 unlocked) 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]]
 103 INPUT/OUTPUT FORMAT
 104 -------------------
 105
 106 `git credential` reads and/or writes (depending on the action used)
 107 credential information in its standard input/output. This information
 108 can correspond either to keys for which `git credential` will obtain
 109 the login information (e.g. host, protocol, path), or to the actual
 110 credential data to be obtained (username/password).
 111
 112 The credential is split into a set of named attributes, with one
 113 attribute per line. Each attribute is specified by a key-value pair,
 114 separated by an `=` (equals) sign, followed by a newline.
 115
 116 The key may contain any bytes except `=`, newline, or NUL. The value may
 117 contain any bytes except newline or NUL.  A line, including the trailing
 118 newline, may not exceed 65535 bytes in order to allow implementations to
 119 parse efficiently.
 120
 121 Attributes with keys that end with C-style array brackets `[]` can have
 122 multiple values. Each instance of a multi-valued attribute forms an
 123 ordered list of values - the order of the repeated attributes defines
 124 the order of the values. An empty multi-valued attribute (`key[]=\n`)
 125 acts to clear any previous entries and reset the list.
 126
 127 In all cases, all bytes are treated as-is (i.e., there is no quoting,
 128 and one cannot transmit a value with newline or NUL in it). The list of
 129 attributes is terminated by a blank line or end-of-file.
 130
 131 Git 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 +
 178 Note that specifying a protocol is mandatory and if the URL
 179 doesn't specify a hostname (e.g., "cert:///path/to/file") the
 180 credential will contain a hostname attribute whose value is an
 181 empty string.
 182 +
 183 Components which are missing from the URL (e.g., there is no
 184 username 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 +
 193 This value should not be sent unless the appropriate capability (see below) is
 194 provided 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 +
 202 This value should not be sent unless the appropriate capability (see below) is
 203 provided 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 +
 213 The credential helper will still be invoked with `store` or `erase` so that it
 214 can determine whether the operation was successful.
 215 +
 216 This value should not be sent unless the appropriate capability (see below) is
 217 provided 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 +
 225 This value should not be sent unless the appropriate capability (see below) is
 226 provided 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 +
 237 This value should not be sent unless the appropriate capability (see below) is
 238 provided on input.  This attribute is 'one-way' from a credential helper to
 239 pass 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 +
 247 Each 'WWW-Authenticate' header value is passed as a multi-valued
 248 attribute 'wwwauth[]', where the order of the attributes is the same as
 249 they appear in the HTTP response. This attribute is 'one-way' from Git
 250 to 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 +
 259 There are two currently supported capabilities.  The first is `authtype`, which
 260 indicates that the `authtype`, `credential`, and `ephemeral` values are
 261 understood.  The second is `state`, which indicates that the `state[]` and
 262 `continue` values are understood.
 263 +
 264 It is not obligatory to use the additional features just because the capability
 265 is supported, but they should not be provided without the capability.
 266
 267 Unrecognised attributes and capabilities are silently discarded.
 268
 269 [[CAPA-IOFMT]]
 270 CAPABILITY INPUT/OUTPUT FORMAT
 271 ------------------------------
 272
 273 For `git credential capability`, the format is slightly different. First, a
 274 `version 0` announcement is made to indicate the current version of the
 275 protocol, and then each capability is announced with a line like `capability
 276 authtype`. Credential helpers may also implement this format, again with the
 277 `capability` argument. Additional lines may be added in the future; callers
 278 should ignore lines which they don't understand.
 279
 280 Because this is a new part of the credential helper protocol, older versions of
 281 Git, as well as some credential helpers, may not support it.  If a non-zero
 282 exit 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
 285 The intention of this format is to differentiate it from the credential output
 286 in 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
 288 distinct format allows users to continue to use this syntax without having to
 289 worry about correctly implementing capability advertisements or accidentally
 290 confusing callers querying for capabilities.
 291
 292 GIT
 293 ---
 294 Part of the linkgit:git[1] suite