Merge branch 'jc/doc-diff-blobs'
[gitweb.git] / Documentation / git-credential.txt
index e70ff899d36eab6f6c59e6891d15aee5baa46752..810e957124feeb383e14e860aa1df46f99a03b5a 100644 (file)
@@ -3,7 +3,7 @@ git-credential(1)
 
 NAME
 ----
-git-credential - retrieve and store user credentials
+git-credential - Retrieve and store user credentials
 
 SYNOPSIS
 --------
@@ -64,12 +64,20 @@ infomation it has):
 
   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,
@@ -86,30 +94,28 @@ unlocked) before it returned `password=secr3t`.
      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`::
 
@@ -134,3 +140,15 @@ sense when dealing with a non-network 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.