Re: [PATCH 06/13] docs: indicate new credential protocol fields
Show 22 quoted lines
> Tell users that they can continue to use a username and password even if
> the new capability is supported.
>
> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
> ---
> Documentation/git-credential.txt | 34 +++++++++++++++++++++++++++++++-
> 1 file changed, 33 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt
> index 918a0aa42b..f3ed3a82fa 100644
> --- a/Documentation/git-credential.txt
> +++ b/Documentation/git-credential.txt
> @@ -178,6 +178,24 @@ 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`, `digest`, and `ntlm`,
> + although the latter two are 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).
How about adding 'bearer' to this list? Popular hosts Bitbucket https://bitbucket.org and Gitea/Forgejo (such as https://codeberg.org) support Bearer auth with OAuth tokens.
Show 8 quoted lines
> ++
> +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.
A credential protocol attribute named 'credential' is confusing. How about 'authorization' since it determines the HTTP Authorization header? This detail is surely worth mentioning too.
Show 30 quoted lines
> ++
> +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 +207,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` and `credential` 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.
M Hickford <mirth.hickford@gmail.com>