Re: credential-helpers + remote-helper, starting point?

Jeff King [off-list ref] writes:

quoted

+When a function in Git or one of its remote-helpers needs to obtain
+credentials (either by asking the user or by fetching from a store),
+it can call the functions in the C API. These functions will fork a
+new process, and communicate with it by passing command-line arguments
+and then communicating through a pipe (see 'Credential Helpers'
+below).

We might or might not fork a new process. It depends on which helpers
are defined.

OK, so s/will fork/may fork/ may be more appropriate.

quoted

+For example, the execution of a command connecting to an HTTP server
+and using the credential helper "cache" will have the following
+structure:
+
+------------
++-----+ -----> +-----------------+
+| git |  pipe  | git remote-http | --- to HTTP server --->
++-----+ <----- +-----------------+
+                    ^      |
+                    | pipe |
+                    |      v
+             +----------------------+
+             | git credential-cache |
+             +----------------------+
+------------
+
+git remote-http will take care of contacting the HTTP server, do the
+actual authentication and see if it's accepted by the server. The
+credential helper will deal with the credential store (which can be
+done by contacting a keyring daemon) and the prompting if needed.

I feel like adding remote-helpers into the mix just makes the situation
more complex (and necessitates the diagram).

The helper is not strictly needed, but that seems to be a common
situation, so I thought describing the common case made sense.

I think it's important to show the difference between the actual
authentication process (e.g. HTTP) and the credential helper. I took
time to understand the example later:

	credential_fill(&c);
        /* [...] */
	status = send_foo_login(f, c.username, c.password);
	switch (status) {

then I understood that send_foo_login was the one doing the actual
authentication, and that further calls to the credential API was needed
to say how it went. Making explicit the fact that the Git code talks
both the helper and the server on which we are authenticating would have
helped me to understand at least.

I think mentionning the fact that a credential helper may connect to a
keyring daemon was important also. I first read some discussions about
credential helpers thinking that we would have to re-implement the
storing mechanism, and really understood what it was all about when I
saw patches for KDE support for example.

Other than that, I do like your wording. If it was just me, I'd take
your introduction, but keep my example + diagram.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/