| '\" t |
| .\" Title: git-credential |
| .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] |
| .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/> |
| .\" Date: 11/18/2018 |
| .\" Manual: Git Manual |
| .\" Source: Git 2.20.0.rc0 |
| .\" Language: English |
| .\" |
| .TH "GIT\-CREDENTIAL" "1" "11/18/2018" "Git 2\&.20\&.0\&.rc0" "Git Manual" |
| .\" ----------------------------------------------------------------- |
| .\" * Define some portability stuff |
| .\" ----------------------------------------------------------------- |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .\" http://bugs.debian.org/507673 |
| .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .ie \n(.g .ds Aq \(aq |
| .el .ds Aq ' |
| .\" ----------------------------------------------------------------- |
| .\" * set default formatting |
| .\" ----------------------------------------------------------------- |
| .\" disable hyphenation |
| .nh |
| .\" disable justification (adjust text to left margin only) |
| .ad l |
| .\" ----------------------------------------------------------------- |
| .\" * MAIN CONTENT STARTS HERE * |
| .\" ----------------------------------------------------------------- |
| .SH "NAME" |
| git-credential \- Retrieve and store user credentials |
| .SH "SYNOPSIS" |
| .sp |
| .nf |
| git credential <fill|approve|reject> |
| .fi |
| .sp |
| .SH "DESCRIPTION" |
| .sp |
| Git has an internal interface for storing and retrieving credentials from system\-specific helpers, as well as prompting the user for usernames and passwords\&. The git\-credential command exposes this interface to scripts which may want to retrieve, store, or prompt for credentials in the same manner as Git\&. The design of this scriptable interface models the internal C API; see \m[blue]\fBthe Git credential API\fR\m[]\&\s-2\u[1]\d\s+2 for more background on the concepts\&. |
| .sp |
| git\-credential takes an "action" option on the command\-line (one of \fBfill\fR, \fBapprove\fR, or \fBreject\fR) and reads a credential description on stdin (see INPUT/OUTPUT FORMAT)\&. |
| .sp |
| If the action is \fBfill\fR, git\-credential will attempt to add "username" and "password" attributes to the description by reading config files, by contacting any configured credential helpers, or by prompting the user\&. The username and password attributes of the credential description are then printed to stdout together with the attributes already provided\&. |
| .sp |
| If the action is \fBapprove\fR, git\-credential will send the description to any configured credential helpers, which may store the credential for later use\&. |
| .sp |
| If the action is \fBreject\fR, git\-credential will send the description to any configured credential helpers, which may erase any stored credential matching the description\&. |
| .sp |
| If the action is \fBapprove\fR or \fBreject\fR, no output should be emitted\&. |
| .SH "TYPICAL USE OF GIT CREDENTIAL" |
| .sp |
| An application using git\-credential will typically use \fBgit credential\fR following these steps: |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 1.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 1." 4.2 |
| .\} |
| Generate a credential description based on the context\&. |
| .sp |
| For example, if we want a password for |
| \fBhttps://example\&.com/foo\&.git\fR, we might generate the following credential description (don\(cqt forget the blank line at the end; it tells |
| \fBgit credential\fR |
| that the application finished feeding all the information it has): |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| protocol=https |
| host=example\&.com |
| path=foo\&.git |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 2.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 2." 4.2 |
| .\} |
| Ask git\-credential to give us a username and password for this description\&. This is done by running |
| \fBgit credential fill\fR, feeding the description from step (1) to its standard input\&. The complete credential description (including the credential per se, i\&.e\&. the login and password) will be produced on standard output, like: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| protocol=https |
| host=example\&.com |
| username=bob |
| password=secr3t |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| In most cases, this means the attributes given in the input will be repeated in the output, but Git may also modify the credential description, for example by removing the |
| \fBpath\fR |
| attribute when the protocol is HTTP(s) and |
| \fBcredential\&.useHttpPath\fR |
| is false\&. |
| .sp |
| If the |
| \fBgit credential\fR |
| knew about the password, this step may not have involved the user actually typing this password (the user may have typed a password to unlock the keychain instead, or no user interaction was done if the keychain was already unlocked) before it returned |
| \fBpassword=secr3t\fR\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 3.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 3." 4.2 |
| .\} |
| Use the credential (e\&.g\&., access the URL with the username and password from step (2)), and see if it\(cqs accepted\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 4.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 4." 4.2 |
| .\} |
| Report on the success or failure of the password\&. If the credential allowed the operation to complete successfully, then it can be marked with an "approve" action to tell |
| \fBgit credential\fR |
| to reuse it in its next invocation\&. If the credential was rejected during the operation, use the "reject" action so that |
| \fBgit credential\fR |
| will ask for a new password in its next invocation\&. In either case, |
| \fBgit credential\fR |
| should be fed with the credential description obtained from step (2) (which also contain the ones provided in step (1))\&. |
| .RE |
| .SH "INPUT/OUTPUT FORMAT" |
| .sp |
| \fBgit credential\fR reads and/or writes (depending on the action used) credential information in its standard input/output\&. This information can correspond either to keys for which \fBgit credential\fR will obtain the login/password information (e\&.g\&. host, protocol, path), or to the actual credential data to be obtained (login/password)\&. |
| .sp |
| The credential is split into a set of named attributes, with one attribute per line\&. Each attribute is specified by a key\-value pair, separated by an \fB=\fR (equals) sign, followed by a newline\&. The key may contain any bytes except \fB=\fR, newline, or NUL\&. The value may contain any bytes except newline or NUL\&. In both cases, all bytes are treated as\-is (i\&.e\&., there is no quoting, and one cannot transmit a value with newline or NUL in it)\&. The list of attributes is terminated by a blank line or end\-of\-file\&. Git understands the following attributes: |
| .PP |
| \fBprotocol\fR |
| .RS 4 |
| The protocol over which the credential will be used (e\&.g\&., |
| \fBhttps\fR)\&. |
| .RE |
| .PP |
| \fBhost\fR |
| .RS 4 |
| The remote hostname for a network credential\&. |
| .RE |
| .PP |
| \fBpath\fR |
| .RS 4 |
| The path with which the credential will be used\&. E\&.g\&., for accessing a remote https repository, this will be the repository\(cqs path on the server\&. |
| .RE |
| .PP |
| \fBusername\fR |
| .RS 4 |
| The credential\(cqs username, if we already have one (e\&.g\&., from a URL, from the user, or from a previously run helper)\&. |
| .RE |
| .PP |
| \fBpassword\fR |
| .RS 4 |
| The credential\(cqs password, if we are asking it to be stored\&. |
| .RE |
| .PP |
| \fBurl\fR |
| .RS 4 |
| When this special attribute is read by |
| \fBgit credential\fR, the value is parsed as a URL and treated as if its constituent parts were read (e\&.g\&., |
| \fBurl=https://example\&.com\fR |
| would behave as if |
| \fBprotocol=https\fR |
| and |
| \fBhost=example\&.com\fR |
| had been provided)\&. This can help callers avoid parsing URLs themselves\&. Note that any components which are missing from the URL (e\&.g\&., there is no username in the example above) will be set to empty; if you want to provide a URL and override some attributes, provide the URL attribute first, followed by any overrides\&. |
| .RE |
| .SH "NOTES" |
| .IP " 1." 4 |
| the Git credential API |
| .RS 4 |
| \%git-htmldocs/technical/api-credentials.html |
| .RE |