<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect2 SYSTEM "../../../dtd/dblite.dtd">

<sect2 lang="en" id="gitcredentials(7)">
    <title>gitcredentials(7)</title>
    <date>2024-07-02</date>
<revhistory><revision><date>2024-07-02</date></revision></revhistory>
<indexterm>
<primary>gitcredentials(7)</primary>
</indexterm>
<simplesect id="gitcredentials(7)__name">
<title>NAME</title>
<simpara>gitcredentials - Providing usernames and passwords to Git</simpara>
</simplesect>
<simplesect id="gitcredentials(7)__synopsis">
<title>SYNOPSIS</title>
<screen>git config credential.https://example.com.username myusername
git config credential.helper "$helper $options"</screen>
</simplesect>
<simplesect id="gitcredentials(7)__description">
<title>DESCRIPTION</title>
<simpara>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.</simpara>
</simplesect>
<simplesect id="gitcredentials(7)__requesting_credentials">
<title>REQUESTING CREDENTIALS</title>
<simpara>Without any credential helpers defined, Git will try the following
strategies to ask the user for usernames and passwords:</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>
If the <emphasis>GIT_ASKPASS</emphasis> 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.
</simpara>
</listitem>
<listitem>
<simpara>
Otherwise, if the <emphasis>core.askPass</emphasis> configuration variable is set, its
   value is used as above.
</simpara>
</listitem>
<listitem>
<simpara>
Otherwise, if the <emphasis>SSH_ASKPASS</emphasis> environment variable is set, its
   value is used as above.
</simpara>
</listitem>
<listitem>
<simpara>
Otherwise, the user is prompted on the terminal.
</simpara>
</listitem>
</orderedlist>
</simplesect>
<simplesect id="gitcredentials(7)__avoiding_repetition">
<title>AVOIDING REPETITION</title>
<simpara>It can be cumbersome to input the same credentials over and over.  Git
provides two methods to reduce this annoyance:</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>
Static configuration of usernames for a given authentication context.
</simpara>
</listitem>
<listitem>
<simpara>
Credential helpers to cache or store passwords, or to interact with
   a system password wallet or keychain.
</simpara>
</listitem>
</orderedlist>
<simpara>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:</simpara>
<screen>[credential "https://example.com"]
        username = me</screen>
<simpara>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.</simpara>
<simpara>To use a helper, you must first select one to use. Git currently
includes the following helpers:</simpara>
<variablelist>
<varlistentry>
<term>
cache
</term>
<listitem>
<simpara>
        Cache credentials in memory for a short period of time. See
        <xref linkend="git-credential-cache(1)" /> for details.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
store
</term>
<listitem>
<simpara>
        Store credentials indefinitely on disk. See
        <xref linkend="git-credential-store(1)" /> for details.
</simpara>
</listitem>
</varlistentry>
</variablelist>
<simpara>You may also have third-party helpers installed; search for
<emphasis>credential-*</emphasis> in the output of <emphasis>git help -a</emphasis>, 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.</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>
Find a helper.
</simpara>
<screen>$ git help -a | grep credential-
credential-foo</screen>
</listitem>
<listitem>
<simpara>
Read its description.
</simpara>
<screen>$ git help credential-foo</screen>
</listitem>
<listitem>
<simpara>
Tell Git to use it.
</simpara>
<screen>$ git config --global credential.helper foo</screen>
</listitem>
</orderedlist>
<section id="gitcredentials(7)__available_helpers">
<title>Available helpers</title>
<simpara>The community maintains a comprehensive list of Git credential helpers at
<ulink url="https://git-scm.com/doc/credential-helpers">https://git-scm.com/doc/credential-helpers</ulink>.</simpara>
</section>
<section id="gitcredentials(7)__oauth">
<title>OAuth</title>
<simpara>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.</simpara>
</section>
</simplesect>
<simplesect id="gitcredentials(7)__credential_contexts">
<title>CREDENTIAL CONTEXTS</title>
<simpara>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.</simpara>
<simpara>For instance, imagine we are accessing <emphasis>https://example.com/foo.git</emphasis>. 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:</simpara>
<screen>[credential "https://example.com"]
        username = foo</screen>
<simpara>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:</simpara>
<screen>[credential "https://kernel.org"]
        username = foo</screen>
<simpara>because the hostnames differ. Nor would it match <emphasis>foo.example.com</emphasis>; Git
compares hostnames exactly, without considering whether two hosts are part of
the same domain. Likewise, a config entry for <emphasis>http://example.com</emphasis> 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 <emphasis>http.&lt;URL&gt;.*</emphasis>
options.</simpara>
<simpara>If the "pattern" URL does include a path component, then this too must match
exactly: the context <emphasis>https://example.com/bar/baz.git</emphasis> will match a config
entry for <emphasis>https://example.com/bar/baz.git</emphasis> (in addition to matching the config
entry for <emphasis>https://example.com</emphasis>) but will not match a config entry for
<emphasis>https://example.com/bar</emphasis>.</simpara>
</simplesect>
<simplesect id="gitcredentials(7)__configuration_options">
<title>CONFIGURATION OPTIONS</title>
<simpara>Options for a credential context can be configured either in
<emphasis>credential.*</emphasis> (which applies to all credentials), or
<emphasis>credential.&lt;URL&gt;.*</emphasis>, where &lt;URL&gt; matches the context as described
above.</simpara>
<simpara>The following options are available in either location:</simpara>
<variablelist>
<varlistentry>
<term>
helper
</term>
<listitem>
<simpara>
        The name of an external credential helper, and any associated options.
        If the helper name is not an absolute path, then the string <emphasis>git
        credential-</emphasis> is prepended. The resulting string is executed by the
        shell (so, for example, setting this to <emphasis>foo --option=bar</emphasis> will execute
        <emphasis>git credential-foo --option=bar</emphasis> via the shell. See the manual of
        specific helpers for examples of their use.
</simpara>
<simpara>If there are multiple instances of the <emphasis>credential.helper</emphasis> 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.</simpara>
<simpara>If <emphasis>credential.helper</emphasis> 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).</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
username
</term>
<listitem>
<simpara>
        A default username, if one is not provided in the URL.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
useHttpPath
</term>
<listitem>
<simpara>
        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 <emphasis>https://example.com/foo.git</emphasis> will also be used for
        <emphasis>https://example.com/bar.git</emphasis>. If you do want to distinguish these
        cases, set this option to <emphasis>true</emphasis>.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</simplesect>
<simplesect id="gitcredentials(7)__custom_helpers">
<title>CUSTOM HELPERS</title>
<simpara>You can write your own custom helpers to interface with any system in
which you keep credentials.</simpara>
<simpara>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).</simpara>
<simpara>Each helper is specified by a single string in the configuration
variable <emphasis>credential.helper</emphasis> (and others, see <xref linkend="git-config(1)" />).
The string is transformed by Git into a command to be executed using
these rules:</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>
If the helper string begins with "!", it is considered a shell
     snippet, and everything after the "!" becomes the command.
</simpara>
</listitem>
<listitem>
<simpara>
Otherwise, if the helper string begins with an absolute path, the
     verbatim helper string becomes the command.
</simpara>
</listitem>
<listitem>
<simpara>
Otherwise, the string "git credential-" is prepended to the helper
     string, and the result becomes the command.
</simpara>
</listitem>
</orderedlist>
<simpara>The resulting command then has an "operation" argument appended to it
(see below for details), and the result is executed by the shell.</simpara>
<simpara>Here are some example specifications:</simpara>
<screen># 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"</screen>
<simpara>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 <emphasis>$PATH</emphasis> or <emphasis>$GIT_EXEC_PATH</emphasis> during installation, which will allow a
user to enable it with <emphasis>git config credential.helper $NAME</emphasis>.</simpara>
<simpara>When a helper is executed, it will have one "operation" argument
appended to its command line, which is one of:</simpara>
<variablelist>
<varlistentry>
<term>
<emphasis>get</emphasis>
</term>
<listitem>
<simpara>
        Return a matching credential, if any exists.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis>store</emphasis>
</term>
<listitem>
<simpara>
        Store the credential, if applicable to the helper.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis>erase</emphasis>
</term>
<listitem>
<simpara>
        Remove matching credentials, if any, from the helper's storage.
</simpara>
</listitem>
</varlistentry>
</variablelist>
<simpara>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
<emphasis>git credential</emphasis> plumbing command (see the section <emphasis>INPUT/OUTPUT
FORMAT</emphasis> in <xref linkend="git-credential(1)" /> for a detailed specification).</simpara>
<simpara>For a <emphasis>get</emphasis> operation, the helper should produce a list of attributes on
stdout in the same format (see <xref linkend="git-credential(1)" /> 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.</simpara>
<simpara>While it is possible to override all attributes, well behaving helpers
should refrain from doing so for any attribute other than username and
password.</simpara>
<simpara>If a helper outputs a <emphasis>quit</emphasis> attribute with a value of <emphasis>true</emphasis> or <emphasis>1</emphasis>,
no further helpers will be consulted, nor will the user be prompted
(if no credential has been provided, the operation will then fail).</simpara>
<simpara>Similarly, no more helpers will be consulted once both username and
password had been provided.</simpara>
<simpara>For a <emphasis>store</emphasis> or <emphasis>erase</emphasis> operation, the helper's output is ignored.</simpara>
<simpara>If a helper fails to perform the requested operation or needs to notify
the user of a potential issue, it may write to stderr.</simpara>
<simpara>If it does not support the requested operation (e.g., a read-only store
or generator), it should silently ignore the request.</simpara>
<simpara>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).</simpara>
</simplesect>
<simplesect id="gitcredentials(7)__git">
<title>GIT</title>
<simpara>Part of the <xref linkend="git(1)" /> suite</simpara>
</simplesect>
</sect2>
