new repository

1 files changed, 35 insertions, 0 deletions

diff --git a/devdocs/git/gitcredentials.html b/devdocs/git/gitcredentials.html
new file mode 100644
index 00000000..698eeb44
--- /dev/null
+++ b/devdocs/git/gitcredentials.html
@@ -0,0 +1,35 @@
+<h1>gitcredentials</h1>  <h2 id="_name">Name</h2> <div class="sectionbody">  <p>gitcredentials - Providing usernames and passwords to Git</p>  </div>   <h2 id="_synopsis">Synopsis</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre data-language="shell">git config credential.https://example.com.username myusername
+git config credential.helper "$helper $options"</pre> </div> </div> </div>   <h2 id="_description">Description</h2> <div class="sectionbody">  <p>Git will sometimes need credentials from the user in order to perform operations; for example, it may need to ask for a username and password in order to access a remote repository over HTTP. Some remotes accept a personal access token or OAuth access token as a password. This manual describes the mechanisms Git uses to request these credentials, as well as some features to avoid inputting these credentials repeatedly.</p>  </div>   <h2 id="_requesting_credentials">Requesting credentials</h2> <div class="sectionbody">  <p>Without any credential helpers defined, Git will try the following strategies to ask the user for usernames and passwords:</p>  <div class="olist arabic"> <ol class="arabic"> <li> <p>If the <code>GIT_ASKPASS</code> environment variable is set, the program specified by the variable is invoked. A suitable prompt is provided to the program on the command line, and the user’s input is read from its standard output.</p> </li> <li> <p>Otherwise, if the <code>core.askPass</code> configuration variable is set, its value is used as above.</p> </li> <li> <p>Otherwise, if the <code>SSH_ASKPASS</code> environment variable is set, its value is used as above.</p> </li> <li> <p>Otherwise, the user is prompted on the terminal.</p> </li> </ol> </div> </div>   <h2 id="_avoiding_repetition">Avoiding repetition</h2> <div class="sectionbody">  <p>It can be cumbersome to input the same credentials over and over. Git provides two methods to reduce this annoyance:</p>  <div class="olist arabic"> <ol class="arabic"> <li> <p>Static configuration of usernames for a given authentication context.</p> </li> <li> <p>Credential helpers to cache or store passwords, or to interact with a system password wallet or keychain.</p> </li> </ol> </div>  <p>The first is simple and appropriate if you do not have secure storage available for a password. It is generally configured by adding this to your config:</p>  <div class="listingblock"> <div class="content"> <pre>[credential "https://example.com"]
+        username = me</pre> </div> </div>  <p>Credential helpers, on the other hand, are external programs from which Git can request both usernames and passwords; they typically interface with secure storage provided by the OS or other programs. Alternatively, a credential-generating helper might generate credentials for certain servers via some API.</p>   <p>To use a helper, you must first select one to use. Git currently includes the following helpers:</p>  <div class="dlist"> <dl> <dt class="hdlist1" id="Documentation/gitcredentials.txt-cache"> cache </dt> <dd> <p>Cache credentials in memory for a short period of time. See <a href="git-credential-cache">git-credential-cache[1]</a> for details.</p> </dd> <dt class="hdlist1" id="Documentation/gitcredentials.txt-store"> store </dt> <dd> <p>Store credentials indefinitely on disk. See <a href="git-credential-store">git-credential-store[1]</a> for details.</p> </dd> </dl> </div>  <p>You may also have third-party helpers installed; search for <code>credential-*</code> in the output of <code>git help -a</code>, and consult the documentation of individual helpers. Once you have selected a helper, you can tell Git to use it by putting its name into the credential.helper variable.</p>  <div class="olist arabic"> <ol class="arabic"> <li> <p>Find a helper.</p> <div class="listingblock"> <div class="content"> <pre data-language="shell-session">$ git help -a | grep credential-
+credential-foo</pre> </div> </div> </li> <li> <p>Read its description.</p> <div class="listingblock"> <div class="content"> <pre data-language="shell-session">$ git help credential-foo</pre> </div> </div> </li> <li> <p>Tell Git to use it.</p> <div class="listingblock"> <div class="content"> <pre data-language="shell-session">$ git config --global credential.helper foo</pre> </div> </div> </li> </ol> </div> <div class="sect2"> <h3 id="_available_helpers">
+Available helpers</h3>  <p>The community maintains a comprehensive list of Git credential helpers at <a href="https://git-scm.com/doc/credential-helpers" class="bare">https://git-scm.com/doc/credential-helpers</a>.</p>  </div> <div class="sect2"> <h3 id="_oauth">
+OAuth</h3>  <p>An alternative to inputting passwords or personal access tokens is to use an OAuth credential helper. Initial authentication opens a browser window to the host. Subsequent authentication happens in the background. Many popular Git hosts support OAuth.</p>  </div> </div>   <h2 id="_credential_contexts">Credential contexts</h2> <div class="sectionbody">  <p>Git considers each credential to have a context defined by a URL. This context is used to look up context-specific configuration, and is passed to any helpers, which may use it as an index into secure storage.</p>   <p>For instance, imagine we are accessing <code>https://example.com/foo.git</code>. When Git looks into a config file to see if a section matches this context, it will consider the two a match if the context is a more-specific subset of the pattern in the config file. For example, if you have this in your config file:</p>  <div class="listingblock"> <div class="content"> <pre>[credential "https://example.com"]
+        username = foo</pre> </div> </div>  <p>then we will match: both protocols are the same, both hosts are the same, and the "pattern" URL does not care about the path component at all. However, this context would not match:</p>  <div class="listingblock"> <div class="content"> <pre>[credential "https://kernel.org"]
+        username = foo</pre> </div> </div>  <p>because the hostnames differ. Nor would it match <code>foo.example.com</code>; Git compares hostnames exactly, without considering whether two hosts are part of the same domain. Likewise, a config entry for <code>http://example.com</code> would not match: Git compares the protocols exactly. However, you may use wildcards in the domain name and other pattern matching techniques as with the <code>http.&lt;URL&gt;.*</code> options.</p>   <p>If the "pattern" URL does include a path component, then this too must match exactly: the context <code>https://example.com/bar/baz.git</code> will match a config entry for <code>https://example.com/bar/baz.git</code> (in addition to matching the config entry for <code>https://example.com</code>) but will not match a config entry for <code>https://example.com/bar</code>.</p>  </div>   <h2 id="_configuration_options">Configuration options</h2> <div class="sectionbody">  <p>Options for a credential context can be configured either in <code>credential.*</code> (which applies to all credentials), or <code>credential.&lt;URL&gt;.*</code>, where &lt;URL&gt; matches the context as described above.</p>   <p>The following options are available in either location:</p>  <div class="dlist"> <dl> <dt class="hdlist1" id="Documentation/gitcredentials.txt-helper"> helper </dt> <dd> <p>The name of an external credential helper, and any associated options. If the helper name is not an absolute path, then the string <code>git
+credential-</code> is prepended. The resulting string is executed by the shell (so, for example, setting this to <code>foo --option=bar</code> will execute <code>git credential-foo --option=bar</code> via the shell. See the manual of specific helpers for examples of their use.</p>  <p>If there are multiple instances of the <code>credential.helper</code> configuration variable, each helper will be tried in turn, and may provide a username, password, or nothing. Once Git has acquired both a username and a non-expired password, no more helpers will be tried.</p>   <p>If <code>credential.helper</code> is configured to the empty string, this resets the helper list to empty (so you may override a helper set by a lower-priority config file by configuring the empty-string helper, followed by whatever set of helpers you would like).</p>  </dd> <dt class="hdlist1" id="Documentation/gitcredentials.txt-username"> username </dt> <dd> <p>A default username, if one is not provided in the URL.</p> </dd> <dt class="hdlist1" id="Documentation/gitcredentials.txt-useHttpPath"> useHttpPath </dt> <dd> <p>By default, Git does not consider the "path" component of an http URL to be worth matching via external helpers. This means that a credential stored for <code>https://example.com/foo.git</code> will also be used for <code>https://example.com/bar.git</code>. If you do want to distinguish these cases, set this option to <code>true</code>.</p> </dd> </dl> </div> </div>   <h2 id="_custom_helpers">Custom helpers</h2> <div class="sectionbody">  <p>You can write your own custom helpers to interface with any system in which you keep credentials.</p>   <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>   <p>Each helper is specified by a single string in the configuration variable <code>credential.helper</code> (and others, see <a href="git-config">git-config[1]</a>). The string is transformed by Git into a command to be executed using these rules:</p>  <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>  <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>   <p>Here are some example specifications:</p>  <div class="listingblock"> <div class="content"> <pre># run "git credential-foo"
+[credential]
+        helper = foo
+
+# same as above, but pass an argument to the helper
+[credential]
+        helper = "foo --bar=baz"
+
+# the arguments are parsed by the shell, so use shell
+# quoting if necessary
+[credential]
+        helper = "foo --bar='whitespace arg'"
+
+# you can also use an absolute path, which will not use the git wrapper
+[credential]
+        helper = "/path/to/my/helper --with-arguments"
+
+# or you can specify your own shell snippet
+[credential "https://example.com"]
+        username = your_user
+        helper = "!f() { test \"$1\" = get &amp;&amp; echo \"password=$(cat $HOME/.secret)\"; }; f"</pre> </div> </div>  <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>   <p>When a helper is executed, it will have one "operation" argument appended to its command line, which is one of:</p>  <div class="dlist"> <dl> <dt class="hdlist1" id="Documentation/gitcredentials.txt-codegetcode"> <code>get</code> </dt> <dd> <p>Return a matching credential, if any exists.</p> </dd> <dt class="hdlist1" id="Documentation/gitcredentials.txt-codestorecode"> <code>store</code> </dt> <dd> <p>Store the credential, if applicable to the helper.</p> </dd> <dt class="hdlist1" id="Documentation/gitcredentials.txt-codeerasecode"> <code>erase</code> </dt> <dd> <p>Remove matching credentials, if any, from the helper’s storage.</p> </dd> </dl> </div>  <p>The details of the credential will be provided on the helper’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">git-credential[1]</a> for a detailed specification).</p>   <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">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’s credential subsystem. Unrecognised attributes are silently discarded.</p>   <p>While it is possible to override all attributes, well behaving helpers should refrain from doing so for any attribute other than username and password.</p>   <p>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>   <p>Similarly, no more helpers will be consulted once both username and password had been provided.</p>   <p>For a <code>store</code> or <code>erase</code> operation, the helper’s output is ignored.</p>   <p>If a helper fails to perform the requested operation or needs to notify the user of a potential issue, it may write to stderr.</p>   <p>If it does not support the requested operation (e.g., a read-only store or generator), it should silently ignore the request.</p>   <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 class="_attribution">
+  <p class="_attribution-p">
+    &copy; 2012&ndash;2024 Scott Chacon and others<br>Licensed under the MIT License.<br>
+    <a href="https://git-scm.com/docs/gitcredentials" class="_attribution-link">https://git-scm.com/docs/gitcredentials</a>
+  </p>
+</div>