Jeff King <peff@xxxxxxxx> writes: > https://github.com/git/git/blob/master/Documentation/technical/api-credentials.txt I just re-read that document (I had a quick glance only before), and started to understand. I think the document really lacks the "big picture". I took time to understand whether the API was to call credential helpers, or to write a new one. Actually, there are two "API": the C one, and the specification of what may flow on the pipe between the two processes. Perhaps something like this should be added: Subject: [PATCH] credential-helper documentation: show the big picture first --- Documentation/technical/api-credentials.txt | 47 +++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt index 21ca6a2..5a872c0 100644 --- a/Documentation/technical/api-credentials.txt +++ b/Documentation/technical/api-credentials.txt @@ -6,8 +6,40 @@ password credentials from the user (even though credentials in the wider world can take many forms, in this document the word "credential" always refers to a username and password pair). +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). The credential helper process will be in charge of actually +prompting the user and/or storing and fetching the credentials. + +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. + +C API +----- + Data Structures ---------------- +~~~~~~~~~~~~~~~ `struct credential`:: @@ -28,7 +60,7 @@ This struct should always be initialized with `CREDENTIAL_INIT` or Functions ---------- +~~~~~~~~~ `credential_init`:: @@ -72,7 +104,7 @@ Functions Parse a URL into broken-down credential fields. Example -------- +~~~~~~~ The example below shows how the functions of the credential API could be used to login to a fictitious "foo" service on a remote host: @@ -130,6 +162,9 @@ int foo_login(struct foo_connection *f) Credential Helpers ------------------ +Choosing the credential helper command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Credential helpers are programs executed by git to fetch or save credentials from and to long-term storage (where "long-term" is simply longer than a single git process; e.g., credentials may be stored @@ -176,6 +211,9 @@ users by naming their program "git-credential-$NAME", and putting it in the $PATH or $GIT_EXEC_PATH during installation, which will allow a user to enable it with `git config credential.helper $NAME`. +Credential helper command-line arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + When a helper is executed, it will have one "operation" argument appended to its command line, which is one of: @@ -191,6 +229,9 @@ appended to its command line, which is one of: Remove a matching credential, if any, from the helper's storage. +Credential helper protocol +~~~~~~~~~~~~~~~~~~~~~~~~~~ + The details of the credential will be provided on the helper's stdin stream. The credential is split into a set of named attributes. Attributes are provided to the helper, one per line. Each attribute is -- 1.7.10.363.g7fcd3d.dirty Also, shouldn't the documentation about choosing the command name be moved to git-config.txt, to document credential.helper? It really seems to be a user documentation, not a technical one meant for Git developers. > But that is the C API, and I assume you are building on the existing > mediawiki helper that is written in perl. Right. > So I think what you really want is a "git credential" command that > will let scripts hook into the credential API. Something like: > > $ git credential get https://example.com > username=bob > password=secret > [...] This is almost already done by test-credential.c indeed. But that's probably the simplest way to expose the C API to a perl program. > Do you guys want to try writing "git credential" as above? It might be a > fun side project, but I know you are also on a limited timeframe for > your project. I can work on it if you don't have time. I leave it up to the students. -- Matthieu Moy http://www-verimag.imag.fr/~moy/ -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html