Matthieu Moy  committed 2239888

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 <>

  • Participants
  • Parent commits dd4287a
  • Branches master

Comments (0)

Files changed (1)

File Documentation/technical/api-credentials.txt

 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.
+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`::
 	Parse a URL into broken-down credential fields.
 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: