@@ -750,7 +750,7 @@ <h2 id="_synopsis">SYNOPSIS</h2>
750
750
< div class ="sectionbody ">
751
751
< div class ="listingblock ">
752
752
< div class ="content ">
753
- < pre > < code > 'git credential' (fill|approve|reject)</ code > </ pre >
753
+ < pre > < code > 'git credential' (fill|approve|reject|capability )</ code > </ pre >
754
754
</ div > </ div >
755
755
</ div >
756
756
</ div >
@@ -779,6 +779,8 @@ <h2 id="_description">DESCRIPTION</h2>
779
779
< div class ="paragraph "> < p > If the action is < code > reject</ code > , git-credential will send the description to
780
780
any configured credential helpers, which may erase any stored
781
781
credentials matching the description.</ p > </ div >
782
+ < div class ="paragraph "> < p > If the action is < code > capability</ code > , git-credential will announce any capabilities
783
+ it supports to standard output.</ p > </ div >
782
784
< div class ="paragraph "> < p > If the action is < code > approve</ code > or < code > reject</ code > , no output should be emitted.</ p > </ div >
783
785
</ div >
784
786
</ div >
@@ -863,7 +865,9 @@ <h2 id="IOFMT">INPUT/OUTPUT FORMAT</h2>
863
865
attribute per line. Each attribute is specified by a key-value pair,
864
866
separated by an < code > =</ code > (equals) sign, followed by a newline.</ p > </ div >
865
867
< div class ="paragraph "> < p > The key may contain any bytes except < code > =</ code > , newline, or NUL. The value may
866
- contain any bytes except newline or NUL.</ p > </ div >
868
+ contain any bytes except newline or NUL. A line, including the trailing
869
+ newline, may not exceed 65535 bytes in order to allow implementations to
870
+ parse efficiently.</ p > </ div >
867
871
< div class ="paragraph "> < p > Attributes with keys that end with C-style array brackets < code > []</ code > can have
868
872
multiple values. Each instance of a multi-valued attribute forms an
869
873
ordered list of values - the order of the repeated attributes defines
@@ -958,6 +962,80 @@ <h2 id="IOFMT">INPUT/OUTPUT FORMAT</h2>
958
962
username in the example above) will be left unset.</ p > </ div >
959
963
</ dd >
960
964
< dt class ="hdlist1 ">
965
+ < code > authtype</ code >
966
+ </ dt >
967
+ < dd >
968
+ < p >
969
+ This indicates that the authentication scheme in question should be used.
970
+ Common values for HTTP and HTTPS include < code > basic</ code > , < code > bearer</ code > , and < code > digest</ code > ,
971
+ although the latter is insecure and should not be used. If < code > credential</ code >
972
+ is used, this may be set to an arbitrary string suitable for the protocol in
973
+ question (usually HTTP).
974
+ </ p >
975
+ < div class ="paragraph "> < p > This value should not be sent unless the appropriate capability (see below) is
976
+ provided on input.</ p > </ div >
977
+ </ dd >
978
+ < dt class ="hdlist1 ">
979
+ < code > credential</ code >
980
+ </ dt >
981
+ < dd >
982
+ < p >
983
+ The pre-encoded credential, suitable for the protocol in question (usually
984
+ HTTP). If this key is sent, < code > authtype</ code > is mandatory, and < code > username</ code > and
985
+ < code > password</ code > are not used. For HTTP, Git concatenates the < code > authtype</ code > value and
986
+ this value with a single space to determine the < code > Authorization</ code > header.
987
+ </ p >
988
+ < div class ="paragraph "> < p > This value should not be sent unless the appropriate capability (see below) is
989
+ provided on input.</ p > </ div >
990
+ </ dd >
991
+ < dt class ="hdlist1 ">
992
+ < code > ephemeral</ code >
993
+ </ dt >
994
+ < dd >
995
+ < p >
996
+ This boolean value indicates, if true, that the value in the < code > credential</ code >
997
+ field should not be saved by the credential helper because its usefulness is
998
+ limited in time. For example, an HTTP Digest < code > credential</ code > value is computed
999
+ using a nonce and reusing it will not result in successful authentication.
1000
+ This may also be used for situations with short duration (e.g., 24-hour)
1001
+ credentials. The default value is false.
1002
+ </ p >
1003
+ < div class ="paragraph "> < p > The credential helper will still be invoked with < code > store</ code > or < code > erase</ code > so that it
1004
+ can determine whether the operation was successful.</ p > </ div >
1005
+ < div class ="paragraph "> < p > This value should not be sent unless the appropriate capability (see below) is
1006
+ provided on input.</ p > </ div >
1007
+ </ dd >
1008
+ < dt class ="hdlist1 ">
1009
+ < code > state[]</ code >
1010
+ </ dt >
1011
+ < dd >
1012
+ < p >
1013
+ This value provides an opaque state that will be passed back to this helper
1014
+ if it is called again. Each different credential helper may specify this
1015
+ once. The value should include a prefix unique to the credential helper and
1016
+ should ignore values that don’t match its prefix.
1017
+ </ p >
1018
+ < div class ="paragraph "> < p > This value should not be sent unless the appropriate capability (see below) is
1019
+ provided on input.</ p > </ div >
1020
+ </ dd >
1021
+ < dt class ="hdlist1 ">
1022
+ < code > continue</ code >
1023
+ </ dt >
1024
+ < dd >
1025
+ < p >
1026
+ This is a boolean value, which, if enabled, indicates that this
1027
+ authentication is a non-final part of a multistage authentication step. This
1028
+ is common in protocols such as NTLM and Kerberos, where two rounds of client
1029
+ authentication are required, and setting this flag allows the credential
1030
+ helper to implement the multistage authentication step. This flag should
1031
+ only be sent if a further stage is required; that is, if another round of
1032
+ authentication is expected.
1033
+ </ p >
1034
+ < div class ="paragraph "> < p > This value should not be sent unless the appropriate capability (see below) is
1035
+ provided on input. This attribute is < em > one-way</ em > from a credential helper to
1036
+ pass information to Git (or other programs invoking < code > git credential</ code > ).</ p > </ div >
1037
+ </ dd >
1038
+ < dt class ="hdlist1 ">
961
1039
< code > wwwauth[]</ code >
962
1040
</ dt >
963
1041
< dd >
@@ -971,8 +1049,47 @@ <h2 id="IOFMT">INPUT/OUTPUT FORMAT</h2>
971
1049
they appear in the HTTP response. This attribute is < em > one-way</ em > from Git
972
1050
to pass additional information to credential helpers.</ p > </ div >
973
1051
</ dd >
1052
+ < dt class ="hdlist1 ">
1053
+ < code > capability[]</ code >
1054
+ </ dt >
1055
+ < dd >
1056
+ < p >
1057
+ This signals that Git, or the helper, as appropriate, supports the capability
1058
+ in question. This can be used to provide better, more specific data as part
1059
+ of the protocol. A < code > capability[]</ code > directive must precede any value depending
1060
+ on it and these directives < em > should</ em > be the first item announced in the
1061
+ protocol.
1062
+ </ p >
1063
+ < div class ="paragraph "> < p > There are two currently supported capabilities. The first is < code > authtype</ code > , which
1064
+ indicates that the < code > authtype</ code > , < code > credential</ code > , and < code > ephemeral</ code > values are
1065
+ understood. The second is < code > state</ code > , which indicates that the < code > state[]</ code > and
1066
+ < code > continue</ code > values are understood.</ p > </ div >
1067
+ < div class ="paragraph "> < p > It is not obligatory to use the additional features just because the capability
1068
+ is supported, but they should not be provided without the capability.</ p > </ div >
1069
+ </ dd >
974
1070
</ dl > </ div >
975
- < div class ="paragraph "> < p > Unrecognised attributes are silently discarded.</ p > </ div >
1071
+ < div class ="paragraph "> < p > Unrecognised attributes and capabilities are silently discarded.</ p > </ div >
1072
+ </ div >
1073
+ </ div >
1074
+ < div class ="sect1 ">
1075
+ < h2 id ="CAPA-IOFMT "> CAPABILITY INPUT/OUTPUT FORMAT</ h2 >
1076
+ < div class ="sectionbody ">
1077
+ < div class ="paragraph "> < p > For < code > git credential capability</ code > , the format is slightly different. First, a
1078
+ < code > version 0</ code > announcement is made to indicate the current version of the
1079
+ protocol, and then each capability is announced with a line like < code > capability
1080
+ authtype</ code > . Credential helpers may also implement this format, again with the
1081
+ < code > capability</ code > argument. Additional lines may be added in the future; callers
1082
+ should ignore lines which they don’t understand.</ p > </ div >
1083
+ < div class ="paragraph "> < p > Because this is a new part of the credential helper protocol, older versions of
1084
+ Git, as well as some credential helpers, may not support it. If a non-zero
1085
+ exit status is received, or if the first line doesn’t start with the word
1086
+ < code > version</ code > and a space, callers should assume that no capabilities are supported.</ p > </ div >
1087
+ < div class ="paragraph "> < p > The intention of this format is to differentiate it from the credential output
1088
+ in an unambiguous way. It is possible to use very simple credential helpers
1089
+ (e.g., inline shell scripts) which always produce identical output. Using a
1090
+ distinct format allows users to continue to use this syntax without having to
1091
+ worry about correctly implementing capability advertisements or accidentally
1092
+ confusing callers querying for capabilities.</ p > </ div >
976
1093
</ div >
977
1094
</ div >
978
1095
< div class ="sect1 ">
@@ -986,7 +1103,7 @@ <h2 id="_git">GIT</h2>
986
1103
< div id ="footer ">
987
1104
< div id ="footer-text ">
988
1105
Last updated
989
- 2023-10-23 14:43:46 PDT
1106
+ 2024-05-13 12:26:56 PDT
990
1107
</ div >
991
1108
</ div >
992
1109
</ body >
0 commit comments