gitcredentials(7)
=================

NAME
----
gitcredentials - Providing usernames and passwords to Git

SYNOPSIS
--------
------------------
git config credential.https://example.com.username myusername
git config credential.helper "$helper $options"
------------------

DESCRIPTION
-----------

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.

REQUESTING CREDENTIALS
----------------------

Without any credential helpers defined, Git will try the following
strategies to ask the user for usernames and passwords:

1. If the `GIT_ASKPASS` 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.

2. Otherwise, if the `core.askPass` configuration variable is set, its
   value is used as above.

3. Otherwise, if the `SSH_ASKPASS` environment variable is set, its
   value is used as above.

4. Otherwise, the user is prompted on the terminal.

AVOIDING REPETITION
-------------------

It can be cumbersome to input the same credentials over and over.  Git
provides two methods to reduce this annoyance:

1. Static configuration of usernames for a given authentication context.

2. Credential helpers to cache or store passwords, or to interact with
   a system password wallet or keychain.

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:

---------------------------------------
[credential "https://example.com"]
	username = me
---------------------------------------

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.

To use a helper, you must first select one to use (see below for a list).

You may also have third-party helpers installed; search for
`credential-*` in the output of `git help -a`, 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.

1. Find a helper.
+
-------------------------------------------
$ git help -a | grep credential-
credential-foo
-------------------------------------------

2. Read its description.
+
-------------------------------------------
$ git help credential-foo
-------------------------------------------

3. Tell Git to use it.
+
-------------------------------------------
$ git config --global credential.helper foo
-------------------------------------------

=== Available helpers

Git currently includes the following helpers:

cache::

    Cache credentials in memory for a short period of time. See
    linkgit:git-credential-cache[1] for details.

store::

    Store credentials indefinitely on disk. See
    linkgit:git-credential-store[1] for details.

Popular helpers with secure persistent storage include:

    - git-credential-libsecret (Linux)

    - git-credential-osxkeychain (macOS)

    - git-credential-wincred (Windows)

    - https://github.com/git-ecosystem/git-credential-manager[Git Credential Manager] (cross platform, included in Git for Windows)

The community maintains a comprehensive list of Git credential helpers at
https://git-scm.com/doc/credential-helpers.

=== OAuth

An alternative to inputting passwords or personal access tokens is to use an
OAuth credential helper. Initial authentication opens