development/git
development/git
1
0
Fork 0
mirror of https://github.com/git/git synced 2024-08-27 03:29:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'jk/doc-credential-helper' into maint

Browse source 
Docfix.

* jk/doc-credential-helper:
  doc: move credential helper info into gitcredentials(7)
This commit is contained in:
Junio C Hamano 2020-03-17 15:02:26 -07:00
parent 32fc2c6dd6 cc4f2eb828
commit 221887a492
2 changed files with 88 additions and 91 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

89
Documentation/gitcredentials.txt
View file

@ -186,7 +186,94 @@ CUSTOM HELPERS
--------------
You can write your own custom helpers to interface with any system in
which you keep credentials. See credential.h for details.
which you keep credentials.
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
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
these rules:
1. If the helper string begins with "!", it is considered a shell
snippet, and everything after the "!" becomes the command.
2. Otherwise, if the helper string begins with an absolute path, the
verbatim helper string becomes the command.
3. Otherwise, the string "git credential-" is prepended to the helper
string, and the result becomes the command.
The resulting command then has an "operation" argument appended to it
(see below for details), and the result is executed by the shell.
Here are some example specifications:
----------------------------------------------------
# run "git credential-foo"
foo
# same as above, but pass an argument to the helper
foo --bar=baz
# the arguments are parsed by the shell, so use shell
# quoting if necessary
foo --bar="whitespace arg"
# you can also use an absolute path, which will not use the git wrapper
/path/to/my/helper --with-arguments
# or you can specify your own shell snippet
!f() { echo "password=`cat $HOME/.secret`"; }; f
----------------------------------------------------
Generally speaking, rule (3) above is the simplest for users to specify.
Authors of credential helpers should make an effort to assist their
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`.
When a helper is executed, it will have one "operation" argument
appended to its command line, which is one of:
`get`::
Return a matching credential, if any exists.
`store`::
Store the credential, if applicable to the helper.
`erase`::
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 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[1] for a detailed specification).
For a `get` operation, the helper should produce a list of attributes on
stdout in the same format (see linkgit:git-credential[1] for common
attributes). 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. If a helper outputs a
`quit` attribute with a value of `true` or `1`, no further helpers will
be consulted, nor will the user be prompted (if no credential has been
provided, the operation will then fail).
For a `store` or `erase` operation, the helper's output is ignored.
If it fails to perform the requested operation, it may complain to
stderr to inform the user. If it does not support the requested
operation (e.g., a read-only store), it should silently ignore the
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).
GIT
---

90
credential.h
View file

@ -90,96 +90,6 @@
* return status;
* }
* -----------------------------------------------------------------------
*
* Credential Helpers
* ------------------
*
* 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
* 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 Documentation/git-config.txt).
* 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.
*
* 2. Otherwise, if the helper string begins with an absolute path, the
* verbatim helper string becomes the command.
*
* 3. Otherwise, the string "git credential-" is prepended to the helper
* string, and the result becomes the command.
*
* The resulting command then has an "operation" argument appended to it
* (see below for details), and the result is executed by the shell.
*
* Here are some example specifications:
*
* ----------------------------------------------------
* # run "git credential-foo"
* foo
*
* # same as above, but pass an argument to the helper
* foo --bar=baz
*
* # the arguments are parsed by the shell, so use shell
* # quoting if necessary
* foo --bar="whitespace arg"
*
* # you can also use an absolute path, which will not use the git wrapper
* /path/to/my/helper --with-arguments
*
* # or you can specify your own shell snippet
* !f() { echo "password=`cat $HOME/.secret`"; }; f
* ----------------------------------------------------
*
* Generally speaking, rule (3) above is the simplest for users to specify.
* Authors of credential helpers should make an effort to assist their
* 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`.
*
* When a helper is executed, it will have one "operation" argument
* appended to its command line, which is one of:
*
* `get`::
*
* Return a matching credential, if any exists.
*
* `store`::
*
* Store the credential, if applicable to the helper.
*
* `erase`::
*
* 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 exact format is the same as the input/output format of the
* `git credential` plumbing command (see the section `INPUT/OUTPUT
* FORMAT` in Documentation/git-credential.txt 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. If a helper
* outputs a `quit` attribute with a value of `true` or `1`, no further
* helpers will be consulted, nor will the user be prompted (if no
* credential has been provided, the operation will then fail).
*
* For a `store` or `erase` operation, the helper's output is ignored.
* If it fails to perform the requested operation, it may complain to
* stderr to inform the user. If it does not support the requested
* operation (e.g., a read-only store), it should silently ignore the
* 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).
*
*/