mirror of
https://github.com/git/git.git
synced 2026-03-14 18:59:04 +01:00
00b1daa2c1
The functionality for helpers is already there; we just need to give the users a way to turn it on. The new functionality is enabled whenever a caller of the credentials API passes a NULL method list. This will enable it for all current callers (i.e., the http code). Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
115 lines
3.8 KiB
Plaintext
115 lines
3.8 KiB
Plaintext
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.
|