Autogenerated HTML docs for v2.45.0-145-g3e4a2

1 files changed, 121 insertions, 4 deletions

diff --git a/git-credential.html b/git-credential.html
index ce596fc64..eb241d3bd 100644
--- a/git-credential.html
+++ b/git-credential.html
@@ -750,7 +750,7 @@ git-credential(1) Manual Page
 <div class="sectionbody">

 <div class="listingblock">

 <div class="content">

-<pre><code>'git credential' (fill|approve|reject)</code></pre>

+<pre><code>'git credential' (fill|approve|reject|capability)</code></pre>

 </div></div>

 </div>

 </div>

@@ -779,6 +779,8 @@ for later use.</p></div>
 <div class="paragraph"><p>If the action is <code>reject</code>, git-credential will send the description to

 any configured credential helpers, which may erase any stored

 credentials matching the description.</p></div>

+<div class="paragraph"><p>If the action is <code>capability</code>, git-credential will announce any capabilities

+it supports to standard output.</p></div>

 <div class="paragraph"><p>If the action is <code>approve</code> or <code>reject</code>, no output should be emitted.</p></div>

 </div>

 </div>

@@ -863,7 +865,9 @@ credential data to be obtained (username/password).</p></div>
 attribute per line. Each attribute is specified by a key-value pair,

 separated by an <code>=</code> (equals) sign, followed by a newline.</p></div>

 <div class="paragraph"><p>The key may contain any bytes except <code>=</code>, newline, or NUL. The value may

-contain any bytes except newline or NUL.</p></div>

+contain any bytes except newline or NUL.  A line, including the trailing

+newline, may not exceed 65535 bytes in order to allow implementations to

+parse efficiently.</p></div>

 <div class="paragraph"><p>Attributes with keys that end with C-style array brackets <code>[]</code> can have

 multiple values. Each instance of a multi-valued attribute forms an

 ordered list of values - the order of the repeated attributes defines

@@ -958,6 +962,80 @@ empty string.</p></div>
 username in the example above) will be left unset.</p></div>

 </dd>

 <dt class="hdlist1">

+<code>authtype</code>

+</dt>

+<dd>

+<p>

+        This indicates that the authentication scheme in question should be used.

+        Common values for HTTP and HTTPS include <code>basic</code>, <code>bearer</code>, and <code>digest</code>,

+        although the latter is insecure and should not be used.  If <code>credential</code>

+        is used, this may be set to an arbitrary string suitable for the protocol in

+        question (usually HTTP).

+</p>

+<div class="paragraph"><p>This value should not be sent unless the appropriate capability (see below) is

+provided on input.</p></div>

+</dd>

+<dt class="hdlist1">

+<code>credential</code>

+</dt>

+<dd>

+<p>

+        The pre-encoded credential, suitable for the protocol in question (usually

+        HTTP).  If this key is sent, <code>authtype</code> is mandatory, and <code>username</code> and

+        <code>password</code> are not used.  For HTTP, Git concatenates the <code>authtype</code> value and

+        this value with a single space to determine the <code>Authorization</code> header.

+</p>

+<div class="paragraph"><p>This value should not be sent unless the appropriate capability (see below) is

+provided on input.</p></div>

+</dd>

+<dt class="hdlist1">

+<code>ephemeral</code>

+</dt>

+<dd>

+<p>

+        This boolean value indicates, if true, that the value in the <code>credential</code>

+        field should not be saved by the credential helper because its usefulness is

+        limited in time.  For example, an HTTP Digest <code>credential</code> value is computed

+        using a nonce and reusing it will not result in successful authentication.

+        This may also be used for situations with short duration (e.g., 24-hour)

+        credentials.  The default value is false.

+</p>

+<div class="paragraph"><p>The credential helper will still be invoked with <code>store</code> or <code>erase</code> so that it

+can determine whether the operation was successful.</p></div>

+<div class="paragraph"><p>This value should not be sent unless the appropriate capability (see below) is

+provided on input.</p></div>

+</dd>

+<dt class="hdlist1">

+<code>state[]</code>

+</dt>

+<dd>

+<p>

+        This value provides an opaque state that will be passed back to this helper

+        if it is called again.  Each different credential helper may specify this

+        once.  The value should include a prefix unique to the credential helper and

+        should ignore values that don&#8217;t match its prefix.

+</p>

+<div class="paragraph"><p>This value should not be sent unless the appropriate capability (see below) is

+provided on input.</p></div>

+</dd>

+<dt class="hdlist1">

+<code>continue</code>

+</dt>

+<dd>

+<p>

+        This is a boolean value, which, if enabled, indicates that this

+        authentication is a non-final part of a multistage authentication step. This

+        is common in protocols such as NTLM and Kerberos, where two rounds of client

+        authentication are required, and setting this flag allows the credential

+        helper to implement the multistage authentication step.  This flag should

+        only be sent if a further stage is required; that is, if another round of

+        authentication is expected.

+</p>

+<div class="paragraph"><p>This value should not be sent unless the appropriate capability (see below) is

+provided on input.  This attribute is <em>one-way</em> from a credential helper to

+pass information to Git (or other programs invoking <code>git credential</code>).</p></div>

+</dd>

+<dt class="hdlist1">

 <code>wwwauth[]</code>

 </dt>

 <dd>

@@ -971,8 +1049,47 @@ attribute <em>wwwauth[]</em>, where the order of the attributes is the same as
 they appear in the HTTP response. This attribute is <em>one-way</em> from Git

 to pass additional information to credential helpers.</p></div>

 </dd>

+<dt class="hdlist1">

+<code>capability[]</code>

+</dt>

+<dd>

+<p>

+        This signals that Git, or the helper, as appropriate, supports the capability

+        in question.  This can be used to provide better, more specific data as part

+        of the protocol.  A <code>capability[]</code> directive must precede any value depending

+        on it and these directives <em>should</em> be the first item announced in the

+        protocol.

+</p>

+<div class="paragraph"><p>There are two currently supported capabilities.  The first is <code>authtype</code>, which

+indicates that the <code>authtype</code>, <code>credential</code>, and <code>ephemeral</code> values are

+understood.  The second is <code>state</code>, which indicates that the <code>state[]</code> and

+<code>continue</code> values are understood.</p></div>

+<div class="paragraph"><p>It is not obligatory to use the additional features just because the capability

+is supported, but they should not be provided without the capability.</p></div>

+</dd>

 </dl></div>

-<div class="paragraph"><p>Unrecognised attributes are silently discarded.</p></div>

+<div class="paragraph"><p>Unrecognised attributes and capabilities are silently discarded.</p></div>

+</div>

+</div>

+<div class="sect1">

+<h2 id="CAPA-IOFMT">CAPABILITY INPUT/OUTPUT FORMAT</h2>

+<div class="sectionbody">

+<div class="paragraph"><p>For <code>git credential capability</code>, the format is slightly different. First, a

+<code>version 0</code> announcement is made to indicate the current version of the

+protocol, and then each capability is announced with a line like <code>capability

+authtype</code>. Credential helpers may also implement this format, again with the

+<code>capability</code> argument. Additional lines may be added in the future; callers

+should ignore lines which they don&#8217;t understand.</p></div>

+<div class="paragraph"><p>Because this is a new part of the credential helper protocol, older versions of

+Git, as well as some credential helpers, may not support it.  If a non-zero

+exit status is received, or if the first line doesn&#8217;t start with the word

+<code>version</code> and a space, callers should assume that no capabilities are supported.</p></div>

+<div class="paragraph"><p>The intention of this format is to differentiate it from the credential output

+in an unambiguous way.  It is possible to use very simple credential helpers

+(e.g., inline shell scripts) which always produce identical output.  Using a

+distinct format allows users to continue to use this syntax without having to

+worry about correctly implementing capability advertisements or accidentally

+confusing callers querying for capabilities.</p></div>

 </div>

 </div>

 <div class="sect1">

@@ -986,7 +1103,7 @@ to pass additional information to credential helpers.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2023-10-23 14:43:46 PDT

+ 2024-05-13 12:26:56 PDT

 </div>

 </div>

 </body>