@matheusbsbs / matheus-bagliano / commits / a6fc9fd3f4

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 <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Jeff King committed Dec 10, 2011 at 05:31 UTC a6fc9fd3f4b42cd97b5262026e18bd451c28ee3c
3 files changed +195
Documentation/Makefile
+1
@@ -7,6 +7,7 @@ MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \
7 MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \
8 gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \
9 gitdiffcore.txt gitnamespaces.txt gitrevisions.txt gitworkflows.txt
10 +MAN7_TXT += gitcredentials.txt
11
12 MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
13 MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT))
Documentation/config.txt
+23
@@ -832,6 +832,29 @@ commit.template::
832 "{tilde}/" is expanded to the value of `$HOME` and "{tilde}user/" to the
833 specified user's home directory.
834
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 +
858 include::diff-config.txt[]
859
860 difftool.<tool>.path::
Documentation/gitcredentials.txt new
+171
@@ -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