Re: [PATCH 06/13] docs: indicate new credential protocol fields

[M Hickford <mirth.hickford@gmail.com>]

> 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.

> ++
> +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.

> ++
> +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.