You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
183 lines
5.9 KiB
183 lines
5.9 KiB
gitcredentials(7) |
|
================= |
|
|
|
NAME |
|
---- |
|
gitcredentials - providing usernames and passwords to git |
|
|
|
SYNOPSIS |
|
-------- |
|
------------------ |
|
git config credential.https://example.com.username myusername |
|
git config credential.helper "$helper $options" |
|
------------------ |
|
|
|
DESCRIPTION |
|
----------- |
|
|
|
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. |
|
|
|
REQUESTING CREDENTIALS |
|
---------------------- |
|
|
|
Without any credential helpers defined, git will try the following |
|
strategies to ask the user for usernames and passwords: |
|
|
|
1. 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's input is read |
|
from its standard output. |
|
|
|
2. Otherwise, if the `core.askpass` configuration variable is set, its |
|
value is used as above. |
|
|
|
3. Otherwise, if the `SSH_ASKPASS` environment variable is set, its |
|
value is used as above. |
|
|
|
4. Otherwise, the user is prompted on the terminal. |
|
|
|
AVOIDING REPETITION |
|
------------------- |
|
|
|
It can be cumbersome to input the same credentials over and over. Git |
|
provides two methods to reduce this annoyance: |
|
|
|
1. Static configuration of usernames for a given authentication context. |
|
|
|
2. Credential helpers to cache or store passwords, or to interact with |
|
a system password wallet or keychain. |
|
|
|
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: |
|
|
|
--------------------------------------- |
|
[credential "https://example.com"] |
|
username = me |
|
--------------------------------------- |
|
|
|
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. |
|
|
|
To use a helper, you must first select one to use. Git currently |
|
includes the following helpers: |
|
|
|
cache:: |
|
|
|
Cache credentials in memory for a short period of time. See |
|
linkgit:git-credential-cache[1] for details. |
|
|
|
store:: |
|
|
|
Store credentials indefinitely on disk. See |
|
linkgit:git-credential-store[1] for details. |
|
|
|
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. |
|
|
|
1. Find a helper. |
|
+ |
|
------------------------------------------- |
|
$ git help -a | grep credential- |
|
credential-foo |
|
------------------------------------------- |
|
|
|
2. Read its description. |
|
+ |
|
------------------------------------------- |
|
$ git help credential-foo |
|
------------------------------------------- |
|
|
|
3. Tell git to use it. |
|
+ |
|
------------------------------------------- |
|
$ git config --global credential.helper foo |
|
------------------------------------------- |
|
|
|
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. |
|
|
|
|
|
CREDENTIAL CONTEXTS |
|
------------------- |
|
|
|
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. |
|
|
|
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: |
|
|
|
-------------------------------------- |
|
[credential "https://example.com"] |
|
username = foo |
|
-------------------------------------- |
|
|
|
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: |
|
|
|
-------------------------------------- |
|
[credential "https://kernel.org"] |
|
username = foo |
|
-------------------------------------- |
|
|
|
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. |
|
|
|
|
|
CONFIGURATION OPTIONS |
|
--------------------- |
|
|
|
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. |
|
|
|
The following options are available in either location: |
|
|
|
helper:: |
|
|
|
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. |
|
|
|
username:: |
|
|
|
A default username, if one is not provided in the URL. |
|
|
|
useHttpPath:: |
|
|
|
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`. |
|
|
|
|
|
CUSTOM HELPERS |
|
-------------- |
|
|
|
You can write your own custom helpers to interface with any system in |
|
which you keep credentials. See the documentation for git's |
|
link:technical/api-credentials.html[credentials API] for details. |
|
|
|
GIT |
|
--- |
|
Part of the linkgit:git[1] suite
|
|
|