Autogenerated HTML docs for v2.25.1-362-g51ebf

1 files changed, 104 insertions, 2 deletions

diff --git a/gitcredentials.html b/gitcredentials.html
index c95c22002..f44c1ed9b 100644
--- a/gitcredentials.html
+++ b/gitcredentials.html
@@ -977,7 +977,109 @@ useHttpPath
 <h2 id="_custom_helpers">CUSTOM HELPERS</h2>

 <div class="sectionbody">

 <div class="paragraph"><p>You can write your own custom helpers to interface with any system in

-which you keep credentials. See credential.h for details.</p></div>

+which you keep credentials.</p></div>

+<div class="paragraph"><p>Credential helpers are programs executed by Git to fetch or save

+credentials from and to long-term storage (where "long-term" is simply

+longer than a single Git process; e.g., credentials may be stored

+in-memory for a few minutes, or indefinitely on disk).</p></div>

+<div class="paragraph"><p>Each helper is specified by a single string in the configuration

+variable <code>credential.helper</code> (and others, see <a href="git-config.html">git-config(1)</a>).

+The string is transformed by Git into a command to be executed using

+these rules:</p></div>

+<div class="olist arabic"><ol class="arabic">

+<li>

+<p>

+If the helper string begins with "!", it is considered a shell

+     snippet, and everything after the "!" becomes the command.

+</p>

+</li>

+<li>

+<p>

+Otherwise, if the helper string begins with an absolute path, the

+     verbatim helper string becomes the command.

+</p>

+</li>

+<li>

+<p>

+Otherwise, the string "git credential-" is prepended to the helper

+     string, and the result becomes the command.

+</p>

+</li>

+</ol></div>

+<div class="paragraph"><p>The resulting command then has an "operation" argument appended to it

+(see below for details), and the result is executed by the shell.</p></div>

+<div class="paragraph"><p>Here are some example specifications:</p></div>

+<div class="listingblock">

+<div class="content">

+<pre><code># run "git credential-foo"

+foo

+

+# same as above, but pass an argument to the helper

+foo --bar=baz

+

+# the arguments are parsed by the shell, so use shell

+# quoting if necessary

+foo --bar="whitespace arg"

+

+# you can also use an absolute path, which will not use the git wrapper

+/path/to/my/helper --with-arguments

+

+# or you can specify your own shell snippet

+!f() { echo "password=`cat $HOME/.secret`"; }; f</code></pre>

+</div></div>

+<div class="paragraph"><p>Generally speaking, rule (3) above is the simplest for users to specify.

+Authors of credential helpers should make an effort to assist their

+users by naming their program "git-credential-$NAME", and putting it in

+the <code>$PATH</code> or <code>$GIT_EXEC_PATH</code> during installation, which will allow a

+user to enable it with <code>git config credential.helper $NAME</code>.</p></div>

+<div class="paragraph"><p>When a helper is executed, it will have one "operation" argument

+appended to its command line, which is one of:</p></div>

+<div class="dlist"><dl>

+<dt class="hdlist1">

+<code>get</code>

+</dt>

+<dd>

+<p>

+        Return a matching credential, if any exists.

+</p>

+</dd>

+<dt class="hdlist1">

+<code>store</code>

+</dt>

+<dd>

+<p>

+        Store the credential, if applicable to the helper.

+</p>

+</dd>

+<dt class="hdlist1">

+<code>erase</code>

+</dt>

+<dd>

+<p>

+        Remove a matching credential, if any, from the helper&#8217;s storage.

+</p>

+</dd>

+</dl></div>

+<div class="paragraph"><p>The details of the credential will be provided on the helper&#8217;s stdin

+stream. The exact format is the same as the input/output format of the

+<code>git credential</code> plumbing command (see the section <code>INPUT/OUTPUT

+FORMAT</code> in <a href="git-credential.html">git-credential(1)</a> for a detailed specification).</p></div>

+<div class="paragraph"><p>For a <code>get</code> operation, the helper should produce a list of attributes on

+stdout in the same format (see <a href="git-credential.html">git-credential(1)</a> for common

+attributes). A helper is free to produce a subset, or even no values at

+all if it has nothing useful to provide. Any provided attributes will

+overwrite those already known about by Git.  If a helper outputs a

+<code>quit</code> attribute with a value of <code>true</code> or <code>1</code>, no further helpers will

+be consulted, nor will the user be prompted (if no credential has been

+provided, the operation will then fail).</p></div>

+<div class="paragraph"><p>For a <code>store</code> or <code>erase</code> operation, the helper&#8217;s output is ignored.

+If it fails to perform the requested operation, it may complain to

+stderr to inform the user. If it does not support the requested

+operation (e.g., a read-only store), it should silently ignore the

+request.</p></div>

+<div class="paragraph"><p>If a helper receives any other operation, it should silently ignore the

+request. This leaves room for future operations to be added (older

+helpers will just ignore the new requests).</p></div>

 </div>

 </div>

 <div class="sect1">

@@ -991,7 +1093,7 @@ which you keep credentials. See credential.h for details.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2019-12-18 15:04:40 PST

+ 2020-02-17 14:00:37 PST

 </div>

 </div>

 </body>