credential: update gitcredentials documentation
Clarify the expected effect of all attributes and how the helpers are expected to handle them and the context where they operate. While at it, space the descriptions for clarity, and add a paragraph mentioning the early termination in the list processing of helpers, to complement the one about the special "quit" attribute. Signed-off-by: Carlo Marcelo Arenas Belón <carenas@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Carlo Marcelo Arenas Belón committed
May 6, 2020 at 14:47 UTC
4b8938be4c4ef2d87642988f3486bc15c366b617
1 file changed
+18
-8
Documentation/gitcredentials.txt
+18
-8
@@ -262,16 +262,26 @@ For a `get` operation, the helper should produce a list of attributes on
262
stdout in the same format (see linkgit:git-credential[1] for common
263
attributes). A helper is free to produce a subset, or even no values at
264
all if it has nothing useful to provide. Any provided attributes will
265
-overwrite those already known about by Git. If a helper outputs a
266
-`quit` attribute with a value of `true` or `1`, no further helpers will
267
-be consulted, nor will the user be prompted (if no credential has been
268
-provided, the operation will then fail).
265
+overwrite those already known about by Git's credential subsystem.
266
+
267
+While it is possible to override all attributes, well behaving helpers
268
+should refrain from doing so for any attribute other than username and
269
+password.
270
+
271
+If a helper outputs a `quit` attribute with a value of `true` or `1`,
272
+no further helpers will be consulted, nor will the user be prompted
273
+(if no credential has been provided, the operation will then fail).
274
+
275
+Similarly, no more helpers will be consulted once both username and
276
+password had been provided.
277
278
For a `store` or `erase` operation, the helper's output is ignored.
271
-If it fails to perform the requested operation, it may complain to
272
-stderr to inform the user. If it does not support the requested
273
-operation (e.g., a read-only store), it should silently ignore the
274
-request.
279
+
280
+If a helper fails to perform the requested operation or needs to notify
281
+the user of a potential issue, it may write to stderr.
282
+
283
+If it does not support the requested operation (e.g., a read-only store),
284
+it should silently ignore the request.
285
286
If a helper receives any other operation, it should silently ignore the
287
request. This leaves room for future operations to be added (older