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