Skip to content

Commit a6fc9fd

Browse files
peffgitster
peff
authored and
gitster
committed
docs: end-user documentation for the credential subsystem
The credential API and helper format is already defined in technical/api-credentials.txt. This presents the end-user view. Signed-off-by: Jeff King <[email protected]> Signed-off-by: Junio C Hamano <[email protected]>
1 parent a78fbb4 commit a6fc9fd

File tree

3 files changed

+195
-0
lines changed

3 files changed

+195
-0
lines changed

‎Documentation/Makefile

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \
77
MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \
88
gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \
99
gitdiffcore.txt gitnamespaces.txt gitrevisions.txt gitworkflows.txt
10+
MAN7_TXT += gitcredentials.txt
1011

1112
MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
1213
MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT))

‎Documentation/config.txt

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -832,6 +832,29 @@ commit.template::
832832
"{tilde}/" is expanded to the value of `$HOME` and "{tilde}user/" to the
833833
specified user's home directory.
834834

835+
credential.helper::
836+
Specify an external helper to be called when a username or
837+
password credential is needed; the helper may consult external
838+
storage to avoid prompting the user for the credentials. See
839+
linkgit:gitcredentials[7] for details.
840+
841+
credential.useHttpPath::
842+
When acquiring credentials, consider the "path" component of an http
843+
or https URL to be important. Defaults to false. See
844+
linkgit:gitcredentials[7] for more information.
845+
846+
credential.username::
847+
If no username is set for a network authentication, use this username
848+
by default. See credential.<context>.* below, and
849+
linkgit:gitcredentials[7].
850+
851+
credential.<url>.*::
852+
Any of the credential.* options above can be applied selectively to
853+
some credentials. For example "credential.https://example.com.username"
854+
would set the default username only for https connections to
855+
example.com. See linkgit:gitcredentials[7] for details on how URLs are
856+
matched.
857+
835858
include::diff-config.txt[]
836859

837860
difftool.<tool>.path::

‎Documentation/gitcredentials.txt

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
gitcredentials(7)
2+
=================
3+
4+
NAME
5+
----
6+
gitcredentials - providing usernames and passwords to git
7+
8+
SYNOPSIS
9+
--------
10+
------------------
11+
git config credential.https://example.com.username myusername
12+
git config credential.helper "$helper $options"
13+
------------------
14+
15+
DESCRIPTION
16+
-----------
17+
18+
Git will sometimes need credentials from the user in order to perform
19+
operations; for example, it may need to ask for a username and password
20+
in order to access a remote repository over HTTP. This manual describes
21+
the mechanisms git uses to request these credentials, as well as some
22+
features to avoid inputting these credentials repeatedly.
23+
24+
REQUESTING CREDENTIALS
25+
----------------------
26+
27+
Without any credential helpers defined, git will try the following
28+
strategies to ask the user for usernames and passwords:
29+
30+
1. 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+
35+
2. Otherwise, if the `core.askpass` configuration variable is set, its
36+
value is used as above.
37+
38+
3. Otherwise, if the `SSH_ASKPASS` environment variable is set, its
39+
value is used as above.
40+
41+
4. Otherwise, the user is prompted on the terminal.
42+
43+
AVOIDING REPETITION
44+
-------------------
45+
46+
It can be cumbersome to input the same credentials over and over. Git
47+
provides two methods to reduce this annoyance:
48+
49+
1. Static configuration of usernames for a given authentication context.
50+
51+
2. Credential helpers to cache or store passwords, or to interact with
52+
a system password wallet or keychain.
53+
54+
The first is simple and appropriate if you do not have secure storage available
55+
for a password. It is generally configured by adding this to your config:
56+
57+
---------------------------------------
58+
[credential "https://example.com"]
59+
username = me
60+
---------------------------------------
61+
62+
Credential helpers, on the other hand, are external programs from which git can
63+
request both usernames and passwords; they typically interface with secure
64+
storage provided by the OS or other programs.
65+
66+
To use a helper, you must first select one to use. Git does not yet
67+
include any credential helpers, but you may have third-party helpers
68+
installed; search for `credential-*` in the output of `git help -a`, and
69+
consult the documentation of individual helpers. Once you have selected
70+
a helper, you can tell git to use it by putting its name into the
71+
credential.helper variable.
72+
73+
1. Find a helper.
74+
+
75+
-------------------------------------------
76+
$ git help -a | grep credential-
77+
credential-foo
78+
-------------------------------------------
79+
80+
2. Read its description.
81+
+
82+
-------------------------------------------
83+
$ git help credential-foo
84+
-------------------------------------------
85+
86+
3. Tell git to use it.
87+
+
88+
-------------------------------------------
89+
$ git config --global credential.helper foo
90+
-------------------------------------------
91+
92+
If there are multiple instances of the `credential.helper` configuration
93+
variable, each helper will be tried in turn, and may provide a username,
94+
password, or nothing. Once git has acquired both a username and a
95+
password, no more helpers will be tried.
96+
97+
98+
CREDENTIAL CONTEXTS
99+
-------------------
100+
101+
Git considers each credential to have a context defined by a URL. This context
102+
is used to look up context-specific configuration, and is passed to any
103+
helpers, which may use it as an index into secure storage.
104+
105+
For instance, imagine we are accessing `https://example.com/foo.git`. When git
106+
looks into a config file to see if a section matches this context, it will
107+
consider the two a match if the context is a more-specific subset of the
108+
pattern in the config file. For example, if you have this in your config file:
109+
110+
--------------------------------------
111+
[credential "https://example.com"]
112+
username = foo
113+
--------------------------------------
114+
115+
then we will match: both protocols are the same, both hosts are the same, and
116+
the "pattern" URL does not care about the path component at all. However, this
117+
context would not match:
118+
119+
--------------------------------------
120+
[credential "https://kernel.org"]
121+
username = foo
122+
--------------------------------------
123+
124+
because the hostnames differ. Nor would it match `foo.example.com`; git
125+
compares hostnames exactly, without considering whether two hosts are part of
126+
the same domain. Likewise, a config entry for `http://example.com` would not
127+
match: git compares the protocols exactly.
128+
129+
130+
CONFIGURATION OPTIONS
131+
---------------------
132+
133+
Options for a credential context can be configured either in
134+
`credential.\*` (which applies to all credentials), or
135+
`credential.<url>.\*`, where <url> matches the context as described
136+
above.
137+
138+
The following options are available in either location:
139+
140+
helper::
141+
142+
The name of an external credential helper, and any associated options.
143+
If the helper name is not an absolute path, then the string `git
144+
credential-` is prepended. The resulting string is executed by the
145+
shell (so, for example, setting this to `foo --option=bar` will execute
146+
`git credential-foo --option=bar` via the shell. See the manual of
147+
specific helpers for examples of their use.
148+
149+
username::
150+
151+
A default username, if one is not provided in the URL.
152+
153+
useHttpPath::
154+
155+
By default, git does not consider the "path" component of an http URL
156+
to be worth matching via external helpers. This means that a credential
157+
stored for `https://example.com/foo.git` will also be used for
158+
`https://example.com/bar.git`. If you do want to distinguish these
159+
cases, set this option to `true`.
160+
161+
162+
CUSTOM HELPERS
163+
--------------
164+
165+
You can write your own custom helpers to interface with any system in
166+
which you keep credentials. See the documentation for git's
167+
link:technical/api-credentials.html[credentials API] for details.
168+
169+
GIT
170+
---
171+
Part of the linkgit:git[1] suite

0 commit comments

Comments
 (0)