'\" t
.\" Title: gitcredentials
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 08/19/2012
.\" Manual: Git Manual
.\" Source: Git 1.7.12
.\" Language: English
.\"
.TH "GITCREDENTIALS" "7" "08/19/2012" "Git 1\&.7\&.12" "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