docs: indicate new credential protocol fields

[thirdparty/git.git] / Documentation / git-credential.txt

diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt
index 918a0aa42b24156ce814ba61cd2006928807ee08..230ac4c2c3fa6e84d0a0f59a091d9261d3483bfc 100644 (file)
--- a/Documentation/git-credential.txt
+++ b/Documentation/git-credential.txt
@@ -178,6 +178,39 @@ empty string.
 Components which are missing from the URL (e.g., there is no
 username in the example above) will be left unset.
 
+`authtype`::
+       This indicates that the authentication scheme in question should be used.
+       Common values for HTTP and HTTPS include `basic`, `bearer`, and `digest`,
+       although the latter is insecure and should not be used.  If `credential`
+       is used, this may be set to an arbitrary string suitable for the protocol in
+       question (usually HTTP).
++
+This value should not be sent unless the appropriate capability (see below) is
+provided on input.
+
+`credential`::
+       The pre-encoded credential, suitable for the protocol in question (usually
+       HTTP).  If this key is sent, `authtype` is mandatory, and `username` and
+       `password` are not used.  For HTTP, Git concatenates the `authtype` value and
+       this value with a single space to determine the `Authorization` header.
++
+This value should not be sent unless the appropriate capability (see below) is
+provided on input.
+
+`ephemeral`::
+       This boolean value indicates, if true, that the value in the `credential`
+       field should not be saved by the credential helper because its usefulness is
+       limited in time.  For example, an HTTP Digest `credential` value is computed
+       using a nonce and reusing it will not result in successful authentication.
+       This may also be used for situations with short duration (e.g., 24-hour)
+       credentials.  The default value is false.
++
+The credential helper will still be invoked with `store` or `erase` so that it
+can determine whether the operation was successful.
++
+This value should not be sent unless the appropriate capability (see below) is
+provided on input.
+
 `wwwauth[]`::
 
        When an HTTP response is received by Git that includes one or more
@@ -189,7 +222,21 @@ attribute 'wwwauth[]', where the order of the attributes is the same as
 they appear in the HTTP response. This attribute is 'one-way' from Git
 to pass additional information to credential helpers.
 
-Unrecognised attributes are silently discarded.
+`capability[]`::
+       This signals that the caller supports the capability in question.
+       This can be used to provide better, more specific data as part of the
+       protocol.
++
+The only capability currently supported is `authtype`, which indicates that the
+`authtype`, `credential`, and `ephemeral` values are understood.  It is not
+obligatory to use these values in such a case, but they should not be provided
+without this capability.
++
+Callers of `git credential` and credential helpers should emit the
+capabilities they support unconditionally, and Git will gracefully
+handle passing them on.
+
+Unrecognised attributes and capabilities are silently discarded.
 
 GIT
 ---