]> git.ipfire.org Git - thirdparty/git.git/blame - Documentation/gitcredentials.txt
Merge branch 'js/t3404-typofix' into maint
[thirdparty/git.git] / Documentation / gitcredentials.txt
CommitLineData
a6fc9fd3
JK
1gitcredentials(7)
2=================
3
4NAME
5----
2de9b711 6gitcredentials - providing usernames and passwords to Git
a6fc9fd3
JK
7
8SYNOPSIS
9--------
10------------------
11git config credential.https://example.com.username myusername
12git config credential.helper "$helper $options"
13------------------
14
15DESCRIPTION
16-----------
17
18Git will sometimes need credentials from the user in order to perform
19operations; for example, it may need to ask for a username and password
20in order to access a remote repository over HTTP. This manual describes
2de9b711 21the mechanisms Git uses to request these credentials, as well as some
a6fc9fd3
JK
22features to avoid inputting these credentials repeatedly.
23
24REQUESTING CREDENTIALS
25----------------------
26
2de9b711 27Without any credential helpers defined, Git will try the following
a6fc9fd3
JK
28strategies to ask the user for usernames and passwords:
29
301. If the `GIT_ASKPASS` environment variable is set, the program
31 specified by the variable is invoked. A suitable prompt is provided
32 to the program on the command line, and the user's input is read
33 from its standard output.
34
da0005b8 352. Otherwise, if the `core.askPass` configuration variable is set, its
a6fc9fd3
JK
36 value is used as above.
37
383. Otherwise, if the `SSH_ASKPASS` environment variable is set, its
39 value is used as above.
40
414. Otherwise, the user is prompted on the terminal.
42
43AVOIDING REPETITION
44-------------------
45
46It can be cumbersome to input the same credentials over and over. Git
47provides two methods to reduce this annoyance:
48
491. Static configuration of usernames for a given authentication context.
50
512. Credential helpers to cache or store passwords, or to interact with
52 a system password wallet or keychain.
53
54The first is simple and appropriate if you do not have secure storage available
55for a password. It is generally configured by adding this to your config:
56
57---------------------------------------
58[credential "https://example.com"]
59 username = me
60---------------------------------------
61
2de9b711 62Credential helpers, on the other hand, are external programs from which Git can
a6fc9fd3
JK
63request both usernames and passwords; they typically interface with secure
64storage provided by the OS or other programs.
65
e2770979
JK
66To use a helper, you must first select one to use. Git currently
67includes the following helpers:
68
69cache::
70
71 Cache credentials in memory for a short period of time. See
72 linkgit:git-credential-cache[1] for details.
73
71e1b4b6
JK
74store::
75
76 Store credentials indefinitely on disk. See
77 linkgit:git-credential-store[1] for details.
78
e2770979
JK
79You may also have third-party helpers installed; search for
80`credential-*` in the output of `git help -a`, and consult the
81documentation of individual helpers. Once you have selected a helper,
2de9b711 82you can tell Git to use it by putting its name into the
a6fc9fd3
JK
83credential.helper variable.
84
851. Find a helper.
86+
87-------------------------------------------
88$ git help -a | grep credential-
89credential-foo
90-------------------------------------------
91
922. Read its description.
93+
94-------------------------------------------
95$ git help credential-foo
96-------------------------------------------
97
2de9b711 983. Tell Git to use it.
a6fc9fd3
JK
99+
100-------------------------------------------
101$ git config --global credential.helper foo
102-------------------------------------------
103
a6fc9fd3
JK
104
105CREDENTIAL CONTEXTS
106-------------------
107
108Git considers each credential to have a context defined by a URL. This context
109is used to look up context-specific configuration, and is passed to any
110helpers, which may use it as an index into secure storage.
111
2de9b711 112For instance, imagine we are accessing `https://example.com/foo.git`. When Git
a6fc9fd3
JK
113looks into a config file to see if a section matches this context, it will
114consider the two a match if the context is a more-specific subset of the
115pattern in the config file. For example, if you have this in your config file:
116
117--------------------------------------
118[credential "https://example.com"]
119 username = foo
120--------------------------------------
121
122then we will match: both protocols are the same, both hosts are the same, and
123the "pattern" URL does not care about the path component at all. However, this
124context would not match:
125
126--------------------------------------
127[credential "https://kernel.org"]
128 username = foo
129--------------------------------------
130
2de9b711 131because the hostnames differ. Nor would it match `foo.example.com`; Git
a6fc9fd3
JK
132compares hostnames exactly, without considering whether two hosts are part of
133the same domain. Likewise, a config entry for `http://example.com` would not
2de9b711 134match: Git compares the protocols exactly.
a6fc9fd3 135
4ba3c9be
DZ
136If the "pattern" URL does include a path component, then this too must match
137exactly: the context `https://example.com/bar/baz.git` will match a config
138entry for `https://example.com/bar/baz.git` (in addition to matching the config
139entry for `https://example.com`) but will not match a config entry for
140`https://example.com/bar`.
141
a6fc9fd3
JK
142
143CONFIGURATION OPTIONS
144---------------------
145
146Options for a credential context can be configured either in
6cf378f0
JK
147`credential.*` (which applies to all credentials), or
148`credential.<url>.*`, where <url> matches the context as described
a6fc9fd3
JK
149above.
150
151The following options are available in either location:
152
153helper::
154
155 The name of an external credential helper, and any associated options.
156 If the helper name is not an absolute path, then the string `git
157 credential-` is prepended. The resulting string is executed by the
158 shell (so, for example, setting this to `foo --option=bar` will execute
159 `git credential-foo --option=bar` via the shell. See the manual of
160 specific helpers for examples of their use.
515360f9
JN
161+
162If there are multiple instances of the `credential.helper` configuration
163variable, each helper will be tried in turn, and may provide a username,
164password, or nothing. Once Git has acquired both a username and a
165password, no more helpers will be tried.
166+
167If `credential.helper` is configured to the empty string, this resets
168the helper list to empty (so you may override a helper set by a
169lower-priority config file by configuring the empty-string helper,
170followed by whatever set of helpers you would like).
a6fc9fd3
JK
171
172username::
173
174 A default username, if one is not provided in the URL.
175
176useHttpPath::
177
2de9b711 178 By default, Git does not consider the "path" component of an http URL
a6fc9fd3
JK
179 to be worth matching via external helpers. This means that a credential
180 stored for `https://example.com/foo.git` will also be used for
181 `https://example.com/bar.git`. If you do want to distinguish these
182 cases, set this option to `true`.
183
184
185CUSTOM HELPERS
186--------------
187
188You can write your own custom helpers to interface with any system in
2de9b711 189which you keep credentials. See the documentation for Git's
a6fc9fd3
JK
190link:technical/api-credentials.html[credentials API] for details.
191
192GIT
193---
194Part of the linkgit:git[1] suite