From dd4287a2c9e9345e0d48c9aa4ee5c330f50623f4 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Mon, 4 Jun 2012 12:30:04 -0700 Subject: [PATCH 1/4] doc: fix xref link from api docs to manual pages They are one-level above, so refer them as linkgit:../git-foo[n] with "../" Signed-off-by: Junio C Hamano --- Documentation/technical/api-config.txt | 2 +- Documentation/technical/api-merge.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt index edf8dfb99b..bd4d8b8f4f 100644 --- a/Documentation/technical/api-config.txt +++ b/Documentation/technical/api-config.txt @@ -2,7 +2,7 @@ config API ========== The config API gives callers a way to access git configuration files -(and files which have the same syntax). See linkgit:git-config[1] for a +(and files which have the same syntax). See linkgit:../git-config[1] for a discussion of the config file syntax. General Usage diff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt index 9dc1bed768..25158b8dc8 100644 --- a/Documentation/technical/api-merge.txt +++ b/Documentation/technical/api-merge.txt @@ -36,7 +36,7 @@ the operation of a low-level (single file) merge. Some options: ancestors in a recursive merge. If a helper program is specified by the `[merge ""] recursive` configuration, it will - be used (see linkgit:gitattributes[5]). + be used (see linkgit:../gitattributes[5]). `variant`:: Resolve local conflicts automatically in favor From 223988808971eb5429efd914e9e88855ea0b0e01 Mon Sep 17 00:00:00 2001 From: Matthieu Moy Date: Mon, 4 Jun 2012 22:17:42 +0200 Subject: [PATCH 2/4] api-credentials.txt: show the big picture first The API documentation targets two kinds of developers: those using the C API, and those writing remote-helpers. The document was not clear about which part was useful to which category, and for example, the C API could be mistakenly thought as an API for writting remote helpers. Based-on-patch-by: Jeff King Signed-off-by: Matthieu Moy Signed-off-by: Junio C Hamano --- Documentation/technical/api-credentials.txt | 50 +++++++++++++++++++-- 1 file changed, 47 insertions(+), 3 deletions(-) diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt index 21ca6a2553..fb6db22a46 100644 --- a/Documentation/technical/api-credentials.txt +++ b/Documentation/technical/api-credentials.txt @@ -6,8 +6,52 @@ 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). +This document describes two interfaces: the C API that the credential +subsystem provides to the rest of git, and the protocol that git uses to +communicate with system-specific "credential helpers". If you are +writing git code that wants to look up or prompt for credentials, see +the section "C API" below. If you want to write your own helper, see +the section on "Credential Helpers" below. + +Typical setup +------------- + +------------ ++-----------------------+ +| git code (C) |--- to server requiring ---> +| | authentication +|.......................| +| C credential API |--- prompt ---> User ++-----------------------+ + ^ | + | pipe | + | v ++-----------------------+ +| git credential helper | ++-----------------------+ +------------ + +The git code (typically a remote-helper) will call the C API to obtain +credential data like a login/password pair (credential_fill). The +API will itself call a remote helper (e.g. "git credential-cache" or +"git credential-store") that may retrieve credential data from a +store. If the credential helper cannot find the information, the C API +will prompt the user. Then, the caller of the API takes care of +contacting the server, and does the actual authentication. + +C API +----- + +The credential C API is meant to be called by git code which needs to +acquire or store a credential. It is centered around an object +representing a single credential and provides three basic operations: +fill (acquire credentials by calling helpers and/or prompting the user), +approve (mark a credential as successfully used so that it can be stored +for later use), and reject (mark a credential as unsuccessful so that it +can be erased from any persistent storage). + Data Structures ---------------- +~~~~~~~~~~~~~~~ `struct credential`:: @@ -28,7 +72,7 @@ This struct should always be initialized with `CREDENTIAL_INIT` or Functions ---------- +~~~~~~~~~ `credential_init`:: @@ -72,7 +116,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: From 365fc8d56a6fdb5a43c71f1c53cc3a67567bf3a6 Mon Sep 17 00:00:00 2001 From: Matthieu Moy Date: Mon, 4 Jun 2012 22:17:43 +0200 Subject: [PATCH 3/4] api-credentials.txt: mention credential.helper explicitly The name of the configuration variable was mentioned only at the very end of the explanation, in a place specific to a specific rule, hence it was not very clear what the specification was about. Signed-off-by: Matthieu Moy Signed-off-by: Junio C Hamano --- Documentation/technical/api-credentials.txt | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt index fb6db22a46..9a17054b6a 100644 --- a/Documentation/technical/api-credentials.txt +++ b/Documentation/technical/api-credentials.txt @@ -179,8 +179,10 @@ credentials from and to long-term storage (where "long-term" is simply longer than a single git process; e.g., credentials may be stored in-memory for a few minutes, or indefinitely on disk). -Each helper is specified by a single string. The string is transformed -by git into a command to be executed using these rules: +Each helper is specified by a single string in the configuration +variable `credential.helper` (and others, see linkgit:../git-config[1]). +The string is transformed by git into a command to be executed using +these rules: 1. If the helper string begins with "!", it is considered a shell snippet, and everything after the "!" becomes the command. From 04ab6ae7765700375e9442347430fc3a6de40f81 Mon Sep 17 00:00:00 2001 From: Matthieu Moy Date: Mon, 4 Jun 2012 22:17:44 +0200 Subject: [PATCH 4/4] api-credentials.txt: add "see also" section Signed-off-by: Matthieu Moy Signed-off-by: Junio C Hamano --- Documentation/technical/api-credentials.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt index 9a17054b6a..199307ca0a 100644 --- a/Documentation/technical/api-credentials.txt +++ b/Documentation/technical/api-credentials.txt @@ -289,3 +289,10 @@ request. If a helper receives any other operation, it should silently ignore the request. This leaves room for future operations to be added (older helpers will just ignore the new requests). + +See also +-------- + +linkgit:../gitcredentials[7] + +linkgit:../git-config[5] (See configuration variables `credential.*`)