diff options
Diffstat (limited to 'third_party/git/Documentation/gitcredentials.txt')
| -rw-r--r-- | third_party/git/Documentation/gitcredentials.txt | 298 |
1 files changed, 0 insertions, 298 deletions
diff --git a/third_party/git/Documentation/gitcredentials.txt b/third_party/git/Documentation/gitcredentials.txt deleted file mode 100644 index 758bf39ba3..0000000000 --- a/third_party/git/Documentation/gitcredentials.txt +++ /dev/null @@ -1,298 +0,0 @@ -gitcredentials(7) -================= - -NAME ----- -gitcredentials - Providing usernames and passwords to Git - -SYNOPSIS --------- ------------------- -git config credential.https://example.com.username myusername -git config credential.helper "$helper $options" ------------------- - -DESCRIPTION ------------ - -Git will sometimes need credentials from the user in order to perform -operations; for example, it may need to ask for a username and password -in order to access a remote repository over HTTP. This manual describes -the mechanisms Git uses to request these credentials, as well as some -features to avoid inputting these credentials repeatedly. - -REQUESTING CREDENTIALS ----------------------- - -Without any credential helpers defined, Git will try the following -strategies to ask the user for usernames and passwords: - -1. If the `GIT_ASKPASS` environment variable is set, the program - specified by the variable is invoked. A suitable prompt is provided - to the program on the command line, and the user's input is read - from its standard output. - -2. Otherwise, if the `core.askPass` configuration variable is set, its - value is used as above. - -3. Otherwise, if the `SSH_ASKPASS` environment variable is set, its - value is used as above. - -4. Otherwise, the user is prompted on the terminal. - -AVOIDING REPETITION -------------------- - -It can be cumbersome to input the same credentials over and over. Git -provides two methods to reduce this annoyance: - -1. Static configuration of usernames for a given authentication context. - -2. Credential helpers to cache or store passwords, or to interact with - a system password wallet or keychain. - -The first is simple and appropriate if you do not have secure storage available -for a password. It is generally configured by adding this to your config: - ---------------------------------------- -[credential "https://example.com"] - username = me ---------------------------------------- - -Credential helpers, on the other hand, are external programs from which Git can -request both usernames and passwords; they typically interface with secure -storage provided by the OS or other programs. - -To use a helper, you must first select one to use. Git currently -includes the following helpers: - -cache:: - - Cache credentials in memory for a short period of time. See - linkgit:git-credential-cache[1] for details. - -store:: - - Store credentials indefinitely on disk. See - linkgit:git-credential-store[1] for details. - -You may also have third-party helpers installed; search for -`credential-*` in the output of `git help -a`, and consult the -documentation of individual helpers. Once you have selected a helper, -you can tell Git to use it by putting its name into the -credential.helper variable. - -1. Find a helper. -+ -------------------------------------------- -$ git help -a | grep credential- -credential-foo -------------------------------------------- - -2. Read its description. -+ -------------------------------------------- -$ git help credential-foo -------------------------------------------- - -3. Tell Git to use it. -+ -------------------------------------------- -$ git config --global credential.helper foo -------------------------------------------- - - -CREDENTIAL CONTEXTS -------------------- - -Git considers each credential to have a context defined by a URL. This context -is used to look up context-specific configuration, and is passed to any -helpers, which may use it as an index into secure storage. - -For instance, imagine we are accessing `https://example.com/foo.git`. When Git -looks into a config file to see if a section matches this context, it will -consider the two a match if the context is a more-specific subset of the -pattern in the config file. For example, if you have this in your config file: - --------------------------------------- -[credential "https://example.com"] - username = foo --------------------------------------- - -then we will match: both protocols are the same, both hosts are the same, and -the "pattern" URL does not care about the path component at all. However, this -context would not match: - --------------------------------------- -[credential "https://kernel.org"] - username = foo --------------------------------------- - -because the hostnames differ. Nor would it match `foo.example.com`; Git -compares hostnames exactly, without considering whether two hosts are part of -the same domain. Likewise, a config entry for `http://example.com` would not -match: Git compares the protocols exactly. However, you may use wildcards in -the domain name and other pattern matching techniques as with the `http.<url>.*` -options. - -If the "pattern" URL does include a path component, then this too must match -exactly: the context `https://example.com/bar/baz.git` will match a config -entry for `https://example.com/bar/baz.git` (in addition to matching the config -entry for `https://example.com`) but will not match a config entry for -`https://example.com/bar`. - - -CONFIGURATION OPTIONS ---------------------- - -Options for a credential context can be configured either in -`credential.*` (which applies to all credentials), or -`credential.<url>.*`, where <url> matches the context as described -above. - -The following options are available in either location: - -helper:: - - The name of an external credential helper, and any associated options. - If the helper name is not an absolute path, then the string `git - credential-` is prepended. The resulting string is executed by the - shell (so, for example, setting this to `foo --option=bar` will execute - `git credential-foo --option=bar` via the shell. See the manual of - specific helpers for examples of their use. -+ -If there are multiple instances of the `credential.helper` configuration -variable, each helper will be tried in turn, and may provide a username, -password, or nothing. Once Git has acquired both a username and a -password, no more helpers will be tried. -+ -If `credential.helper` is configured to the empty string, this resets -the helper list to empty (so you may override a helper set by a -lower-priority config file by configuring the empty-string helper, -followed by whatever set of helpers you would like). - -username:: - - A default username, if one is not provided in the URL. - -useHttpPath:: - - By default, Git does not consider the "path" component of an http URL - to be worth matching via external helpers. This means that a credential - stored for `https://example.com/foo.git` will also be used for - `https://example.com/bar.git`. If you do want to distinguish these - cases, set this option to `true`. - - -CUSTOM HELPERS --------------- - -You can write your own custom helpers to interface with any system in -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" -[credential] - helper = foo - -# same as above, but pass an argument to the helper -[credential] - helper = "foo --bar=baz" - -# the arguments are parsed by the shell, so use shell -# quoting if necessary -[credential] - helper = "foo --bar='whitespace arg'" - -# you can also use an absolute path, which will not use the git wrapper -[credential] - helper = "/path/to/my/helper --with-arguments" - -# or you can specify your own shell snippet -[credential "https://example.com"] - username = your_user - helper = "!f() { test \"$1\" = get && 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's credential subsystem. - -While it is possible to override all attributes, well behaving helpers -should refrain from doing so for any attribute other than username and -password. - -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). - -Similarly, no more helpers will be consulted once both username and -password had been provided. - -For a `store` or `erase` operation, the helper's output is ignored. - -If a helper fails to perform the requested operation or needs to notify -the user of a potential issue, it may write to stderr. - -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 ---- -Part of the linkgit:git[1] suite |