From 223988808971eb5429efd914e9e88855ea0b0e01 Mon Sep 17 00:00:00 2001 From: Matthieu Moy Date: Mon, 4 Jun 2012 22:17:42 +0200 Subject: 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(-) (limited to 'Documentation/technical/api-credentials.txt') 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: -- cgit v1.2.1 From 365fc8d56a6fdb5a43c71f1c53cc3a67567bf3a6 Mon Sep 17 00:00:00 2001 From: Matthieu Moy Date: Mon, 4 Jun 2012 22:17:43 +0200 Subject: 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(-) (limited to 'Documentation/technical/api-credentials.txt') 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. -- cgit v1.2.1 From 04ab6ae7765700375e9442347430fc3a6de40f81 Mon Sep 17 00:00:00 2001 From: Matthieu Moy Date: Mon, 4 Jun 2012 22:17:44 +0200 Subject: 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(+) (limited to 'Documentation/technical/api-credentials.txt') 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.*`) -- cgit v1.2.1 From fe77b416c774a469a585c4b58fcae5e7a5f3545d Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 7 Jun 2012 23:03:23 +0200 Subject: docs: fix cross-directory linkgit references Most of our documentation is in a single directory, so using linkgit:git-config[1] just generates a relative link in the same directory. However, this is not the case with the API documentation in technical/*, which need to refer to git-config from the parent directory. We can fix this by passing a special prefix attribute when building in a subdirectory, and respecting that prefix in our linkgit definitions. We only have to modify the html linkgit definition. For manpages, we can ignore this for two reasons: 1. we do not generate actual links to the file in manpages, but instead just give the name and section of the linked manpage 2. we do not currently build manpages for subdirectories, only html Signed-off-by: Jeff King Signed-off-by: Matthieu Moy Signed-off-by: Junio C Hamano --- Documentation/technical/api-credentials.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation/technical/api-credentials.txt') diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt index 199307ca0a..4ef1db39ab 100644 --- a/Documentation/technical/api-credentials.txt +++ b/Documentation/technical/api-credentials.txt @@ -180,7 +180,7 @@ 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 in the configuration -variable `credential.helper` (and others, see linkgit:../git-config[1]). +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: @@ -293,6 +293,6 @@ helpers will just ignore the new requests). See also -------- -linkgit:../gitcredentials[7] +linkgit:gitcredentials[7] -linkgit:../git-config[5] (See configuration variables `credential.*`) +linkgit:git-config[5] (See configuration variables `credential.*`) -- cgit v1.2.1 From 317d74be690f68748e8af9844407db3b100d836f Mon Sep 17 00:00:00 2001 From: Matthieu Moy Date: Mon, 11 Jun 2012 19:51:47 +0200 Subject: api-credential.txt: document that helpers field is filled-in automatically It was unclear whether the field was to be specified by the user of the API. Signed-off-by: Matthieu Moy Signed-off-by: Junio C Hamano --- Documentation/technical/api-credentials.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'Documentation/technical/api-credentials.txt') diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt index 4ef1db39ab..adb6f0c896 100644 --- a/Documentation/technical/api-credentials.txt +++ b/Documentation/technical/api-credentials.txt @@ -65,7 +65,10 @@ Data Structures The `helpers` member of the struct is a `string_list` of helpers. Each string specifies an external helper which will be run, in order, to either acquire or store credentials. See the section on credential -helpers below. +helpers below. This list is filled-in by the API functions +according to the corresponding configuration variables before +consulting helpers, so there usually is no need for a caller to +modify the helpers field at all. + This struct should always be initialized with `CREDENTIAL_INIT` or `credential_init`. -- cgit v1.2.1 From e30b2feb1b50c2d14d32dc3e6e41f7b20a677ff2 Mon Sep 17 00:00:00 2001 From: Javier Roucher Iglesias Date: Sun, 24 Jun 2012 13:39:59 +0200 Subject: add 'git credential' plumbing command The credential API is in C, and not available to scripting languages. Expose the functionalities of the API by wrapping them into a new plumbing command "git credentials". In other words, replace the internal "test-credential" by an official Git command. Most documentation writen by: Jeff King Signed-off-by: Pavel Volek Signed-off-by: Kim Thuat Nguyen Signed-off-by: Javier Roucher Iglesias Signed-off-by: Matthieu Moy Signed-off-by: Junio C Hamano --- Documentation/technical/api-credentials.txt | 39 +++-------------------------- 1 file changed, 3 insertions(+), 36 deletions(-) (limited to 'Documentation/technical/api-credentials.txt') diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt index adb6f0c896..5977b58e57 100644 --- a/Documentation/technical/api-credentials.txt +++ b/Documentation/technical/api-credentials.txt @@ -241,42 +241,9 @@ appended to its command line, which is one of: Remove a matching credential, if any, from the helper's storage. 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 -specified by a key-value pair, separated by an `=` (equals) sign, -followed by a newline. The key may contain any bytes except `=`, -newline, or NUL. The value may contain any bytes except newline or NUL. -In both cases, all bytes are treated as-is (i.e., there is no quoting, -and one cannot transmit a value with newline or NUL in it). The list of -attributes is terminated by a blank line or end-of-file. - -Git will send the following attributes (but may not send all of -them for a given credential; for example, a `host` attribute makes no -sense when dealing with a non-network protocol): - -`protocol`:: - - The protocol over which the credential will be used (e.g., - `https`). - -`host`:: - - The remote hostname for a network credential. - -`path`:: - - The path with which the credential will be used. E.g., for - accessing a remote https repository, this will be the - repository's path on the server. - -`username`:: - - The credential's username, if we already have one (e.g., from a - URL, from the user, or from a previously run helper). - -`password`:: - - The credential's password, if we are asking it to be stored. +stream. The exact format is the same as the input/output format of the +`git credential` plumbing command (see the section `INPUT/OUTPUT +FORMAT` in linkgit:git-credential[7] for a detailed specification). For a `get` operation, the helper should produce a list of attributes on stdout in the same format. A helper is free to produce a subset, or -- cgit v1.2.1 From 2de9b71138171dca7279db3b3fe67e868c76d921 Mon Sep 17 00:00:00 2001 From: Thomas Ackermann Date: Mon, 21 Jan 2013 20:17:53 +0100 Subject: Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann Signed-off-by: Junio C Hamano --- Documentation/technical/api-credentials.txt | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'Documentation/technical/api-credentials.txt') diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt index 5977b58e57..516fda7412 100644 --- a/Documentation/technical/api-credentials.txt +++ b/Documentation/technical/api-credentials.txt @@ -7,9 +7,9 @@ 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 +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 +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. @@ -18,7 +18,7 @@ Typical setup ------------ +-----------------------+ -| git code (C) |--- to server requiring ---> +| Git code (C) |--- to server requiring ---> | | authentication |.......................| | C credential API |--- prompt ---> User @@ -27,11 +27,11 @@ Typical setup | pipe | | v +-----------------------+ -| git credential helper | +| Git credential helper | +-----------------------+ ------------ -The git code (typically a remote-helper) will call the C API to obtain +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 @@ -42,7 +42,7 @@ 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 +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), @@ -177,14 +177,14 @@ int foo_login(struct foo_connection *f) Credential Helpers ------------------ -Credential helpers are programs executed by git to fetch or save +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 +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 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 +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 @@ -248,7 +248,7 @@ FORMAT` in linkgit:git-credential[7] for a detailed specification). For a `get` operation, the helper should produce a list of attributes on stdout in the same format. 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. +attributes will overwrite those already known about by Git. For a `store` or `erase` operation, the helper's output is ignored. If it fails to perform the requested operation, it may complain to -- cgit v1.2.1 From e1c3bf496f494e60e781c8dd0ec3d799ea48722c Mon Sep 17 00:00:00 2001 From: Stefano Lattarini Date: Fri, 12 Apr 2013 00:36:10 +0200 Subject: doc: various spelling fixes Most of these were found using Lucas De Marchi's codespell tool. Signed-off-by: Stefano Lattarini Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/technical/api-credentials.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/technical/api-credentials.txt') diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt index 516fda7412..c1b42a40d3 100644 --- a/Documentation/technical/api-credentials.txt +++ b/Documentation/technical/api-credentials.txt @@ -160,7 +160,7 @@ int foo_login(struct foo_connection *f) break; default: /* - * Some other error occured. We don't know if the + * Some other error occurred. We don't know if the * credential is good or bad, so report nothing to the * credential subsystem. */ -- cgit v1.2.1