[v2,3/4] credential: update gitcredentials documentation
diff mbox series

Message ID 20200506214726.81854-4-carenas@gmail.com
State New
Headers show
Series
  • credential: documentation updates for maint
Related show

Commit Message

Carlo Marcelo Arenas Belón May 6, 2020, 9:47 p.m. UTC
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>
---
 Documentation/gitcredentials.txt | 25 +++++++++++++++++--------
 1 file changed, 17 insertions(+), 8 deletions(-)

Comments

Jeff King May 7, 2020, 8:54 p.m. UTC | #1
On Wed, May 06, 2020 at 02:47:25PM -0700, Carlo Marcelo Arenas Belón wrote:

> +While it is possible to override all attributes, well behaving helpers
> +should refrain from doing so for anyone other than username and password.

The earlier versions said "any attributes other than..." which I think
is a bit more precise than "anyone".

Other than that, this looks good to me.

-Peff
Junio C Hamano May 7, 2020, 9:02 p.m. UTC | #2
Jeff King <peff@peff.net> writes:

> On Wed, May 06, 2020 at 02:47:25PM -0700, Carlo Marcelo Arenas Belón wrote:
>
>> +While it is possible to override all attributes, well behaving helpers
>> +should refrain from doing so for anyone other than username and password.
>
> The earlier versions said "any attributes other than..." which I think
> is a bit more precise than "anyone".
>
> Other than that, this looks good to me.

Will locally tweak; thanks.

Patch
diff mbox series

diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt
index 1814d2d23c..05e544ee49 100644
--- a/Documentation/gitcredentials.txt
+++ b/Documentation/gitcredentials.txt
@@ -262,16 +262,25 @@  For a `get` operation, the helper should produce a list of attributes on
 stdout in the same format (see linkgit:git-credential[1] for common
 attributes). A helper is free to produce a subset, or even no values at
 all if it has nothing useful to provide. Any provided attributes will
-overwrite those already known about by Git.  If a helper outputs a
-`quit` attribute with a value of `true` or `1`, no further helpers will
-be consulted, nor will the user be prompted (if no credential has been
-provided, the operation will then fail).
+overwrite those already known about by Git's credential subsystem.
+
+While it is possible to override all attributes, well behaving helpers
+should refrain from doing so for anyone other than username and password.
+
+If a helper outputs a `quit` attribute with a value of `true` or `1`,
+no further helpers will be consulted, nor will the user be prompted
+(if no credential has been provided, the operation will then fail).
+
+Similarly, no more helpers will be consulted once both username and
+password had been provided.
 
 For a `store` or `erase` operation, the helper's output is ignored.
-If it fails to perform the requested operation, it may complain to
-stderr to inform the user. If it does not support the requested
-operation (e.g., a read-only store), it should silently ignore the
-request.
+
+If a helper fails to perform the requested operation or needs to notify
+the user of a potential issue, it may write to stderr.
+
+If it does not support the requested operation (e.g., a read-only store),
+it should silently ignore the request.
 
 If a helper receives any other operation, it should silently ignore the
 request. This leaves room for future operations to be added (older