| '\" t |
| .\" Title: gitcredentials |
| .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] |
| .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/> |
| .\" Date: 06/08/2020 |
| .\" Manual: Git Manual |
| .\" Source: Git 2.27.0.83.g0313f36c6e |
| .\" Language: English |
| .\" |
| .TH "GITCREDENTIALS" "7" "06/08/2020" "Git 2\&.27\&.0\&.83\&.g0313f36" "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" |
| gitcredentials \- providing usernames and passwords to Git |
| .SH "SYNOPSIS" |
| .sp |
| .nf |
| git config credential\&.https://example\&.com\&.username myusername |
| git config credential\&.helper "$helper $options" |
| .fi |
| .sp |
| .SH "DESCRIPTION" |
| .sp |
| 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\&. This manual describes the mechanisms Git uses to request these credentials, as well as some features to avoid inputting these credentials repeatedly\&. |
| .SH "REQUESTING CREDENTIALS" |
| .sp |
| Without any credential helpers defined, Git will try the following strategies to ask the user for usernames and passwords: |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 1.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 1." 4.2 |
| .\} |
| If the |
| \fBGIT_ASKPASS\fR |
| 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\(cqs input is read from its standard output\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 2.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 2." 4.2 |
| .\} |
| Otherwise, if the |
| \fBcore\&.askPass\fR |
| configuration variable is set, its value is used as above\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 3.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 3." 4.2 |
| .\} |
| Otherwise, if the |
| \fBSSH_ASKPASS\fR |
| environment variable is set, its value is used as above\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 4.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 4." 4.2 |
| .\} |
| Otherwise, the user is prompted on the terminal\&. |
| .RE |
| .SH "AVOIDING REPETITION" |
| .sp |
| It can be cumbersome to input the same credentials over and over\&. Git provides two methods to reduce this annoyance: |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 1.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 1." 4.2 |
| .\} |
| Static configuration of usernames for a given authentication context\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 2.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 2." 4.2 |
| .\} |
| Credential helpers to cache or store passwords, or to interact with a system password wallet or keychain\&. |
| .RE |
| .sp |
| 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: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| [credential "https://example\&.com"] |
| username = me |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .sp |
| 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\&. |
| .sp |
| To use a helper, you must first select one to use\&. Git currently includes the following helpers: |
| .PP |
| cache |
| .RS 4 |
| Cache credentials in memory for a short period of time\&. See |
| \fBgit-credential-cache\fR(1) |
| for details\&. |
| .RE |
| .PP |
| store |
| .RS 4 |
| Store credentials indefinitely on disk\&. See |
| \fBgit-credential-store\fR(1) |
| for details\&. |
| .RE |
| .sp |
| You may also have third\-party helpers installed; search for \fBcredential\-*\fR in the output of \fBgit help \-a\fR, 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\&. |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 1.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 1." 4.2 |
| .\} |
| Find a helper\&. |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| $ git help \-a | grep credential\- |
| credential\-foo |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 2.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 2." 4.2 |
| .\} |
| Read its description\&. |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| $ git help credential\-foo |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 3.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 3." 4.2 |
| .\} |
| Tell Git to use it\&. |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| $ git config \-\-global credential\&.helper foo |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .RE |
| .SH "CREDENTIAL CONTEXTS" |
| .sp |
| Git considers each credential to have a context defined by a URL\&. This context is used to look up context\-specific configuration, and is passed to any helpers, which may use it as an index into secure storage\&. |
| .sp |
| For instance, imagine we are accessing \fBhttps://example\&.com/foo\&.git\fR\&. When Git looks into a config file to see if a section matches this context, it will consider the two a match if the context is a more\-specific subset of the pattern in the config file\&. For example, if you have this in your config file: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| [credential "https://example\&.com"] |
| username = foo |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .sp |
| then we will match: both protocols are the same, both hosts are the same, and the "pattern" URL does not care about the path component at all\&. However, this context would not match: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| [credential "https://kernel\&.org"] |
| username = foo |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .sp |
| because the hostnames differ\&. Nor would it match \fBfoo\&.example\&.com\fR; Git compares hostnames exactly, without considering whether two hosts are part of the same domain\&. Likewise, a config entry for \fBhttp://example\&.com\fR would not match: Git compares the protocols exactly\&. However, you may use wildcards in the domain name and other pattern matching techniques as with the \fBhttp\&.<url>\&.*\fR options\&. |
| .sp |
| If the "pattern" URL does include a path component, then this too must match exactly: the context \fBhttps://example\&.com/bar/baz\&.git\fR will match a config entry for \fBhttps://example\&.com/bar/baz\&.git\fR (in addition to matching the config entry for \fBhttps://example\&.com\fR) but will not match a config entry for \fBhttps://example\&.com/bar\fR\&. |
| .SH "CONFIGURATION OPTIONS" |
| .sp |
| Options for a credential context can be configured either in \fBcredential\&.*\fR (which applies to all credentials), or \fBcredential\&.<url>\&.*\fR, where <url> matches the context as described above\&. |
| .sp |
| The following options are available in either location: |
| .PP |
| helper |
| .RS 4 |
| The name of an external credential helper, and any associated options\&. If the helper name is not an absolute path, then the string |
| \fBgit credential\-\fR |
| is prepended\&. The resulting string is executed by the shell (so, for example, setting this to |
| \fBfoo \-\-option=bar\fR |
| will execute |
| \fBgit credential\-foo \-\-option=bar\fR |
| via the shell\&. See the manual of specific helpers for examples of their use\&. |
| .sp |
| If there are multiple instances of the |
| \fBcredential\&.helper\fR |
| configuration variable, each helper will be tried in turn, and may provide a username, password, or nothing\&. Once Git has acquired both a username and a password, no more helpers will be tried\&. |
| .sp |
| If |
| \fBcredential\&.helper\fR |
| is configured to the empty string, this resets the helper list to empty (so you may override a helper set by a lower\-priority config file by configuring the empty\-string helper, followed by whatever set of helpers you would like)\&. |
| .RE |
| .PP |
| username |
| .RS 4 |
| A default username, if one is not provided in the URL\&. |
| .RE |
| .PP |
| useHttpPath |
| .RS 4 |
| By default, Git does not consider the "path" component of an http URL to be worth matching via external helpers\&. This means that a credential stored for |
| \fBhttps://example\&.com/foo\&.git\fR |
| will also be used for |
| \fBhttps://example\&.com/bar\&.git\fR\&. If you do want to distinguish these cases, set this option to |
| \fBtrue\fR\&. |
| .RE |
| .SH "CUSTOM HELPERS" |
| .sp |
| You can write your own custom helpers to interface with any system in which you keep credentials\&. |
| .sp |
| 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)\&. |
| .sp |
| Each helper is specified by a single string in the configuration variable \fBcredential\&.helper\fR (and others, see \fBgit-config\fR(1))\&. The string is transformed by Git into a command to be executed using these rules: |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 1.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 1." 4.2 |
| .\} |
| If the helper string begins with "!", it is considered a shell snippet, and everything after the "!" becomes the command\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 2.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 2." 4.2 |
| .\} |
| Otherwise, if the helper string begins with an absolute path, the verbatim helper string becomes the command\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 3.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 3." 4.2 |
| .\} |
| Otherwise, the string "git credential\-" is prepended to the helper string, and the result becomes the command\&. |
| .RE |
| .sp |
| The resulting command then has an "operation" argument appended to it (see below for details), and the result is executed by the shell\&. |
| .sp |
| Here are some example specifications: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| # run "git credential\-foo" |
| [credential] |
| helper = foo |
| |
| # same as above, but pass an argument to the helper |
| [credential] |
| helper = "foo \-\-bar=baz" |
| |
| # the arguments are parsed by the shell, so use shell |
| # quoting if necessary |
| [credential] |
| helper = "foo \-\-bar=\(aqwhitespace arg\(aq" |
| |
| # you can also use an absolute path, which will not use the git wrapper |
| [credential] |
| helper = "/path/to/my/helper \-\-with\-arguments" |
| |
| # or you can specify your own shell snippet |
| [credential "https://example\&.com"] |
| username = your_user |
| helper = "!f() { test \e"$1\e" = get && echo \e"password=$(cat $HOME/\&.secret)\e"; }; f" |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .sp |
| 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 \fB$PATH\fR or \fB$GIT_EXEC_PATH\fR during installation, which will allow a user to enable it with \fBgit config credential\&.helper $NAME\fR\&. |
| .sp |
| When a helper is executed, it will have one "operation" argument appended to its command line, which is one of: |
| .PP |
| \fBget\fR |
| .RS 4 |
| Return a matching credential, if any exists\&. |
| .RE |
| .PP |
| \fBstore\fR |
| .RS 4 |
| Store the credential, if applicable to the helper\&. |
| .RE |
| .PP |
| \fBerase\fR |
| .RS 4 |
| Remove a matching credential, if any, from the helper\(cqs storage\&. |
| .RE |
| .sp |
| The details of the credential will be provided on the helper\(cqs stdin stream\&. The exact format is the same as the input/output format of the \fBgit credential\fR plumbing command (see the section \fBINPUT/OUTPUT FORMAT\fR in \fBgit-credential\fR(1) for a detailed specification)\&. |
| .sp |
| For a \fBget\fR operation, the helper should produce a list of attributes on stdout in the same format (see \fBgit-credential\fR(1) for common attributes)\&. 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\(cqs credential subsystem\&. |
| .sp |
| While it is possible to override all attributes, well behaving helpers should refrain from doing so for any attribute other than username and password\&. |
| .sp |
| If a helper outputs a \fBquit\fR attribute with a value of \fBtrue\fR or \fB1\fR, no further helpers will be consulted, nor will the user be prompted (if no credential has been provided, the operation will then fail)\&. |
| .sp |
| Similarly, no more helpers will be consulted once both username and password had been provided\&. |
| .sp |
| For a \fBstore\fR or \fBerase\fR operation, the helper\(cqs output is ignored\&. |
| .sp |
| If a helper fails to perform the requested operation or needs to notify the user of a potential issue, it may write to stderr\&. |
| .sp |
| If it does not support the requested operation (e\&.g\&., a read\-only store), it should silently ignore the request\&. |
| .sp |
| 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)\&. |
| .SH "GIT" |
| .sp |
| Part of the \fBgit\fR(1) suite |