credentials API
===============

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

Data Structures
---------------

`struct credential`::

	This struct represents a single username/password combination.
	The `username` and `password` fields should be heap-allocated
	strings (or NULL if they are not yet known). The `unique` field,
	if non-NULL, should be a heap-allocated string indicating a
	unique context for this credential (e.g., a protocol and server
	name for a remote credential). The `description` field, if
	non-NULL, should point to a string containing a human-readable
	description of this credential.

`struct string_list methods`::

	The credential functions take a `string_list` of methods for
	acquiring credentials. Each string specifies an external
	helper which will be run, in order, to acquire credentials,
	until both a username and password have been acquired. A NULL
	parameter means to use the default list (as configured by
	`credential.helper`); an empty list indicates that the internal
	`credential_getpass` function should be used.


Functions
---------

`credential_fill_gently`::

	Attempt to fill the username and password fields of the passed
	credential struct. If they cannot be filled after trying each
	available method, returns -1. Otherwise, returns 0.

`credential_fill`::

	Like `credential_fill_gently`, but `die()` if credentials cannot
	be gathered.

`credential_reject`::

	Inform the credential subsystem that the provided credentials
	have been rejected. This will clear the username and password
	fields in `struct credential`, as well as notify any helpers of
	the rejection (which may, for example, purge the invalid
	credentials from storage).

`credential_getpass`::

	Fetch credentials from the user either using an "askpass" helper
	(see the discussion of core.askpass and GIT_ASKPASS in
	linkgit:git-config[1] and linkgit:git[1], respectively) or by
	prompting the user via the terminal.


Credential Helpers
------------------

Credential helpers are programs executed by git to fetch credentials
from storage or from the user. The default behavior when no helpers are
defined is to use the internal `credential_askpass` function.

When a helper is executed, it may receive the following options on the
command line:

`--reject`::

	Specify that the provided credential has been rejected; the
	helper may take appropriate action to purge any credential
	storage or cache. If this option is not given, the helper should
	assume a credential is being requested.

`--description=<X>`::

	`<X>` will contain a human-readable description of the
	credential being requested. If this option is not given, no
	description is available.

`--unique=<X>`::

	`<X>` will contain a token to uniquely identify the context of
	the credential (e.g., a host name for network authentication).
	If this option is not given, no context is available.

`--username=<X>`::

	`<X>` will contain the username requested by the user. If this
	option is not given, no username is available, and the helper
	should provide both a username and password.

The helper should produce a list of items on stdout, each followed by a
newline character. Each item should consist of a key-value pair, separated
by an `=` (equals) sign. The value may contain any bytes except a
newline. When reading the response, git understands the following keys:

`username`::

	The username part of the credential. If a username was given to
	the helper via `--username`, the new value will override it.

`password`::

	The password part of the credential.

It is perfectly acceptable for a helper to provide only part of a
credential, or nothing at all.