gitcredentials.7 (15364B)
- '\" t
- .\" Title: gitcredentials
- .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
- .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
- .\" Date: 2025-03-14
- .\" Manual: Git Manual
- .\" Source: Git 2.49.0
- .\" Language: English
- .\"
- .TH "GITCREDENTIALS" "7" "2025-03-14" "Git 2\&.49\&.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
- .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\&. Some remotes accept a personal access token or OAuth access token as a password\&. 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
- 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\&. Alternatively, a credential\-generating helper might generate credentials for certain servers via some API\&.
- .sp
- To use a helper, you must first select one to use (see below for a list)\&.
- .sp
- You may also have third\-party helpers installed; search for \fBcredential\-\fR* in the output of \fBgit\fR \fBhelp\fR \fB\-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
- .\}
- .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
- .\}
- .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
- .\}
- .RE
- .SS "Available helpers"
- .sp
- 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
- Popular helpers with secure persistent storage include:
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- git\-credential\-libsecret (Linux)
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- git\-credential\-osxkeychain (macOS)
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- git\-credential\-wincred (Windows)
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- \m[blue]\fBGit Credential Manager\fR\m[]\&\s-2\u[1]\d\s+2
- (cross platform, included in Git for Windows)
- .RE
- .sp
- The community maintains a comprehensive list of Git credential helpers at \m[blue]\fBhttps://git\-scm\&.com/doc/credential\-helpers\fR\m[]\&.
- .SS "OAuth"
- .sp
- An alternative to inputting passwords or personal access tokens is to use an OAuth credential helper\&. Initial authentication opens a browser window to the host\&. Subsequent authentication happens in the background\&. Many popular Git hosts support OAuth\&.
- .sp
- Popular helpers with OAuth support include:
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- \m[blue]\fBGit Credential Manager\fR\m[]\&\s-2\u[1]\d\s+2
- (cross platform, included in Git for Windows)
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- \m[blue]\fBgit\-credential\-oauth\fR\m[]\&\s-2\u[2]\d\s+2
- (cross platform, included in many Linux distributions)
- .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
- 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
- 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\&.\fR\fI<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\&.\fR\fI<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\fR
- \fBcredential\-\fR
- is prepended\&. The resulting string is executed by the shell (so, for example, setting this to
- \fBfoo\fR
- \fB\-\-option=bar\fR
- will execute
- \fBgit\fR
- \fBcredential\-foo\fR
- \fB\-\-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 non\-expired 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"
- # store helper (discouraged) with custom location for the db file;
- # use `\-\-file ~/\&.git\-secret\&.txt`, rather than `\-\-file=~/\&.git\-secret\&.txt`,
- # to allow the shell to expand tilde to the home directory\&.
- [credential]
- helper = "store \-\-file ~/\&.git\-secret\&.txt"
- # 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
- 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\fR \fBconfig\fR \fBcredential\&.helper\fR \fB$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 matching credentials, 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\fR \fBcredential\fR plumbing command (see the section \fBINPUT/OUTPUT\fR \fBFORMAT\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\&. Unrecognised attributes are silently discarded\&.
- .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 or generator), 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
- .SH "NOTES"
- .IP " 1." 4
- Git Credential Manager
- .RS 4
- \%https://github.com/git-ecosystem/git-credential-manager
- .RE
- .IP " 2." 4
- git-credential-oauth
- .RS 4
- \%https://github.com/hickford/git-credential-oauth
- .RE