Re: [PATCH 06/13] docs: indicate new credential protocol fields
From: M Hickford <hidden>
Date: 2024-03-25 23:16:20
quoted hunk ↗ jump to hunk
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 <redacted> --- 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.
quoted hunk ↗ jump to hunk
++ +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.