NAME
----
-git-credential - retrieve and store user credentials
+git-credential - Retrieve and store user credentials
SYNOPSIS
--------
2. Ask git-credential to give us a username and password for this
description. This is done by running `git credential fill`,
- feeding the description from step (1) to its standard input. The
- credential will be produced on standard output, like:
+ feeding the description from step (1) to its standard input. The complete
+ credential description (including the credential per se, i.e. the
+ login and password) will be produced on standard output, like:
+ protocol=https
+ host=example.com
username=bob
password=secr3t
+
+In most cases, this means the attributes given in the input will be
+repeated in the output, but git may also modify the credential
+description, for example by removing the `path` attribute when the
+protocol is HTTP(s) and `credential.useHttpPath` is false.
++
If the `git credential` knew about the password, this step may
not have involved the user actually typing this password (the
user may have typed a password to unlock the keychain instead,
was rejected during the operation, use the "reject" action so
that `git credential` will ask for a new password in its next
invocation. In either case, `git credential` should be fed with
- the credential description obtained from step (2) together with
- the ones already provided in step (1).
+ the credential description obtained from step (2) (which also
+ contain the ones provided in step (1)).
[[IOFMT]]
INPUT/OUTPUT FORMAT
-------------------
`git credential` reads and/or writes (depending on the action used)
-credential information in its standard input/output. These information
+credential information in its standard input/output. This information
can correspond either to keys for which `git credential` will obtain
the login/password information (e.g. host, protocol, path), or to the
actual credential data to be obtained (login/password).
-The credential is split into a set of named attributes.
-Attributes are provided to the helper, one per line. Each attribute is
+The credential is split into a set of named attributes, with one
+attribute per line. Each attribute is
specified by a key-value pair, separated by an `=` (equals) sign,
followed by a newline. The key may contain any bytes except `=`,
newline, or NUL. The value may contain any bytes except newline or NUL.
In both cases, all bytes are treated as-is (i.e., there is no quoting,
and one cannot transmit a value with newline or NUL in it). The list of
attributes is terminated by a blank line or end-of-file.
-Git will send the following attributes (but may not send all of
-them for a given credential; for example, a `host` attribute makes no
-sense when dealing with a non-network protocol):
+Git understands the following attributes:
`protocol`::
`password`::
The credential's password, if we are asking it to be stored.
+
+`url`::
+
+ When this special attribute is read by `git credential`, the
+ value is parsed as a URL and treated as if its constituent parts
+ were read (e.g., `url=https://example.com` would behave as if
+ `protocol=https` and `host=example.com` had been provided). This
+ can help callers avoid parsing URLs themselves. Note that any
+ components which are missing from the URL (e.g., there is no
+ username in the example above) will be set to empty; if you want
+ to provide a URL and override some attributes, provide the URL
+ attribute first, followed by any overrides.