The credentials API provides an abstracted way of gathering username and password credentials from the user (even though credentials in the wider world can take many forms, in this document the word "credential" always refers to a username and password pair).

This document describes two interfaces: the C API that the credential subsystem provides to the rest of Git, and the protocol that Git uses to communicate with system-specific "credential helpers". If you are writing Git code that wants to look up or prompt for credentials, see the section "C API" below. If you want to write your own helper, see the section on "Credential Helpers" below.

+-----------------------+
| Git code (C)          |--- to server requiring --->
|                       |        authentication
|.......................|
| C credential API      |--- prompt ---> User
+-----------------------+
        ^      |
        | pipe |
        |      v
+-----------------------+
| Git credential helper |
+-----------------------+

The Git code (typically a remote-helper) will call the C API to obtain credential data like a login/password pair (credential_fill). The API will itself call a remote helper (e.g. "git credential-cache" or "git credential-store") that may retrieve credential data from a store. If the credential helper cannot find the information, the C API will prompt the user. Then, the caller of the API takes care of contacting the server, and does the actual authentication.

The credential C API is meant to be called by Git code which needs to acquire or store a credential. It is centered around an object representing a single credential and provides three basic operations: fill (acquire credentials by calling helpers and/or prompting the user), approve (mark a credential as successfully used so that it can be stored for later use), and reject (mark a credential as unsuccessful so that it can be erased from any persistent storage).

int foo_login(struct foo_connection *f)
{
        int status;
        /*
         * Create a credential with some context; we don't yet know the
         * username or password.
         */

        struct credential c = CREDENTIAL_INIT;
        c.protocol = xstrdup("foo");
        c.host = xstrdup(f->hostname);

        /*
         * Fill in the username and password fields by contacting
         * helpers and/or asking the user. The function will die if it
         * fails.
         */
        credential_fill(&c);

        /*
         * Otherwise, we have a username and password. Try to use it.
         */
        status = send_foo_login(f, c.username, c.password);
        switch (status) {
        case FOO_OK:
                /* It worked. Store the credential for later use. */
                credential_accept(&c);
                break;
        case FOO_BAD_LOGIN:
                /* Erase the credential from storage so we don't try it
                 * again. */
                credential_reject(&c);
                break;
        default:
                /*
                 * Some other error occurred. We don't know if the
                 * credential is good or bad, so report nothing to the
                 * credential subsystem.
                 */
        }

        /* Free any associated resources. */
        credential_clear(&c);

        return status;
}

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).

Each helper is specified by a single string in the configuration variable credential.helper (and others, see git-config[1]). The string is transformed by Git into a command to be executed using these rules:

The resulting command then has an "operation" argument appended to it (see below for details), and the result is executed by the shell.

Here are some example specifications:

# 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

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 $PATH or $GIT_EXEC_PATH during installation, which will allow a user to enable it with git config credential.helper $NAME.

When a helper is executed, it will have one "operation" argument appended to its command line, which is one of:

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 git credential plumbing command (see the section INPUT/OUTPUT FORMAT in git-credential[1] for a detailed specification).

For a get operation, the helper should produce a list of attributes on stdout in the same format. 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 quit attribute with a value of true or 1, no further helpers will be consulted, nor will the user be prompted (if no credential has been provided, the operation will then fail).

For a store or erase operation, the helper’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.

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).

gitcredentials[7]

git-config[1] (See configuration variables credential.*)