'\" t .\" Title: gitcredentials .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/> .\" Date: 04/30/2015 .\" Manual: Git Manual .\" Source: Git 2.4.0 .\" Language: English .\" .TH "GITCREDENTIALS" "7" "04/30/2015" "Git 2\&.4\&.0" "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 GIT_ASKPASS 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 core\&.askPass 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 SSH_ASKPASS 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 credential\-* in the output of git help \-a, 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 .sp If there are multiple instances of the credential\&.helper 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\&. .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 https://example\&.com/foo\&.git\&. 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 foo\&.example\&.com; Git compares hostnames exactly, without considering whether two hosts are part of the same domain\&. Likewise, a config entry for http://example\&.com would not match: Git compares the protocols exactly\&. .SH "CONFIGURATION OPTIONS" .sp Options for a credential context can be configured either in credential\&.* (which applies to all credentials), or credential\&.<url>\&.*, 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 git credential\- is prepended\&. The resulting string is executed by the shell (so, for example, setting this to foo \-\-option=bar will execute git credential\-foo \-\-option=bar via the shell\&. See the manual of specific helpers for examples of their use\&. .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 https://example\&.com/foo\&.git will also be used for https://example\&.com/bar\&.git\&. If you do want to distinguish these cases, set this option to true\&. .RE .SH "CUSTOM HELPERS" .sp You can write your own custom helpers to interface with any system in which you keep credentials\&. See the documentation for Git\(cqs \m[blue]\fBcredentials API\fR\m[]\&\s-2\u[1]\d\s+2 for details\&. .SH "GIT" .sp Part of the \fBgit\fR(1) suite .SH "NOTES" .IP " 1." 4 credentials API .RS 4 \%git-htmldocs/technical/api-credentials.html .RE