doc: move credential helper info into gitcredentials(7)
The details of how credential helpers can be called or implemented were originally covered in Documentation/technical/. Those are topics that end users might care about (and we even referenced them in the credentials manpage), but those docs typically don't ship as part of the end user documentation, making them less useful. This situation got slightly worse recently in f3b9055624 (credential: move doc to credential.h, 2019-11-17), where we moved them into the C header file, making them even harder to find. So let's move put this information into the gitcredentials(7) documentation, which is meant to describe the overall concepts of our credential handling. This was already pointing to the API docs for these concepts, so we can just include it inline instead. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jeff King committed
Feb 14, 2020 at 13:54 UTC
cc4f2eb8281ab9f6f71694834ea01c93572d224a
2 files changed
+88
-91
Documentation/gitcredentials.txt
+88
-1
@@ -186,7 +186,94 @@ CUSTOM HELPERS
186
--------------
187
188
You can write your own custom helpers to interface with any system in
189
-which you keep credentials. See credential.h for details.
189
+which you keep credentials.
190
+
191
+Credential helpers are programs executed by Git to fetch or save
192
+credentials from and to long-term storage (where "long-term" is simply
193
+longer than a single Git process; e.g., credentials may be stored
194
+in-memory for a few minutes, or indefinitely on disk).
195
+
196
+Each helper is specified by a single string in the configuration
197
+variable `credential.helper` (and others, see linkgit:git-config[1]).
198
+The string is transformed by Git into a command to be executed using
199
+these rules:
200
+
201
+ 1. If the helper string begins with "!", it is considered a shell
202
+ snippet, and everything after the "!" becomes the command.
203
+
204
+ 2. Otherwise, if the helper string begins with an absolute path, the
205
+ verbatim helper string becomes the command.
206
+
207
+ 3. Otherwise, the string "git credential-" is prepended to the helper
208
+ string, and the result becomes the command.
209
+
210
+The resulting command then has an "operation" argument appended to it
211
+(see below for details), and the result is executed by the shell.
212
+
213
+Here are some example specifications:
214
+
215
+----------------------------------------------------
216
+# run "git credential-foo"
217
+foo
218
+
219
+# same as above, but pass an argument to the helper
220
+foo --bar=baz
221
+
222
+# the arguments are parsed by the shell, so use shell
223
+# quoting if necessary
224
+foo --bar="whitespace arg"
225
+
226
+# you can also use an absolute path, which will not use the git wrapper
227
+/path/to/my/helper --with-arguments
228
+
229
+# or you can specify your own shell snippet
230
+!f() { echo "password=`cat $HOME/.secret`"; }; f
231
+----------------------------------------------------
232
+
233
+Generally speaking, rule (3) above is the simplest for users to specify.
234
+Authors of credential helpers should make an effort to assist their
235
+users by naming their program "git-credential-$NAME", and putting it in
236
+the `$PATH` or `$GIT_EXEC_PATH` during installation, which will allow a
237
+user to enable it with `git config credential.helper $NAME`.
238
+
239
+When a helper is executed, it will have one "operation" argument
240
+appended to its command line, which is one of:
241
+
242
+`get`::
243
+
244
+ Return a matching credential, if any exists.
245
+
246
+`store`::
247
+
248
+ Store the credential, if applicable to the helper.
249
+
250
+`erase`::
251
+
252
+ Remove a matching credential, if any, from the helper's storage.
253
+
254
+The details of the credential will be provided on the helper's stdin
255
+stream. The exact format is the same as the input/output format of the
256
+`git credential` plumbing command (see the section `INPUT/OUTPUT
257
+FORMAT` in linkgit:git-credential[1] for a detailed specification).
258
+
259
+For a `get` operation, the helper should produce a list of attributes on
260
+stdout in the same format (see linkgit:git-credential[1] for common
261
+attributes). A helper is free to produce a subset, or even no values at
262
+all if it has nothing useful to provide. Any provided attributes will
263
+overwrite those already known about by Git. If a helper outputs a
264
+`quit` attribute with a value of `true` or `1`, no further helpers will
265
+be consulted, nor will the user be prompted (if no credential has been
266
+provided, the operation will then fail).
267
+
268
+For a `store` or `erase` operation, the helper's output is ignored.
269
+If it fails to perform the requested operation, it may complain to
270
+stderr to inform the user. If it does not support the requested
271
+operation (e.g., a read-only store), it should silently ignore the
272
+request.
273
+
274
+If a helper receives any other operation, it should silently ignore the
275
+request. This leaves room for future operations to be added (older
276
+helpers will just ignore the new requests).
277
278
GIT
279
---
credential.h
-90
@@ -90,96 +90,6 @@
90
* return status;
91
* }
92
* -----------------------------------------------------------------------
93
- *
94
- * Credential Helpers
95
- * ------------------
96
- *
97
- * Credential helpers are programs executed by Git to fetch or save
98
- * credentials from and to long-term storage (where "long-term" is simply
99
- * longer than a single Git process; e.g., credentials may be stored
100
- * in-memory for a few minutes, or indefinitely on disk).
101
- *
102
- * Each helper is specified by a single string in the configuration
103
- * variable `credential.helper` (and others, see Documentation/git-config.txt).
104
- * The string is transformed by Git into a command to be executed using
105
- * these rules:
106
- *
107
- * 1. If the helper string begins with "!", it is considered a shell
108
- * snippet, and everything after the "!" becomes the command.
109
- *
110
- * 2. Otherwise, if the helper string begins with an absolute path, the
111
- * verbatim helper string becomes the command.
112
- *
113
- * 3. Otherwise, the string "git credential-" is prepended to the helper
114
- * string, and the result becomes the command.
115
- *
116
- * The resulting command then has an "operation" argument appended to it
117
- * (see below for details), and the result is executed by the shell.
118
- *
119
- * Here are some example specifications:
120
- *
121
- * ----------------------------------------------------
122
- * # run "git credential-foo"
123
- * foo
124
- *
125
- * # same as above, but pass an argument to the helper
126
- * foo --bar=baz
127
- *
128
- * # the arguments are parsed by the shell, so use shell
129
- * # quoting if necessary
130
- * foo --bar="whitespace arg"
131
- *
132
- * # you can also use an absolute path, which will not use the git wrapper
133
- * /path/to/my/helper --with-arguments
134
- *
135
- * # or you can specify your own shell snippet
136
- * !f() { echo "password=`cat $HOME/.secret`"; }; f
137
- * ----------------------------------------------------
138
- *
139
- * Generally speaking, rule (3) above is the simplest for users to specify.
140
- * Authors of credential helpers should make an effort to assist their
141
- * users by naming their program "git-credential-$NAME", and putting it in
142
- * the $PATH or $GIT_EXEC_PATH during installation, which will allow a user
143
- * to enable it with `git config credential.helper $NAME`.
144
- *
145
- * When a helper is executed, it will have one "operation" argument
146
- * appended to its command line, which is one of:
147
- *
148
- * `get`::
149
- *
150
- * Return a matching credential, if any exists.
151
- *
152
- * `store`::
153
- *
154
- * Store the credential, if applicable to the helper.
155
- *
156
- * `erase`::
157
- *
158
- * Remove a matching credential, if any, from the helper's storage.
159
- *
160
- * The details of the credential will be provided on the helper's stdin
161
- * stream. The exact format is the same as the input/output format of the
162
- * `git credential` plumbing command (see the section `INPUT/OUTPUT
163
- * FORMAT` in Documentation/git-credential.txt for a detailed specification).
164
- *
165
- * For a `get` operation, the helper should produce a list of attributes
166
- * on stdout in the same format. A helper is free to produce a subset, or
167
- * even no values at all if it has nothing useful to provide. Any provided
168
- * attributes will overwrite those already known about by Git. If a helper
169
- * outputs a `quit` attribute with a value of `true` or `1`, no further
170
- * helpers will be consulted, nor will the user be prompted (if no
171
- * credential has been provided, the operation will then fail).
172
- *
173
- * For a `store` or `erase` operation, the helper's output is ignored.
174
- * If it fails to perform the requested operation, it may complain to
175
- * stderr to inform the user. If it does not support the requested
176
- * operation (e.g., a read-only store), it should silently ignore the
177
- * request.
178
- *
179
- * If a helper receives any other operation, it should silently ignore the
180
- * request. This leaves room for future operations to be added (older
181
- * helpers will just ignore the new requests).
182
- *
93
*/
94
95