about summary refs log tree commit diff
path: root/third_party/git/Documentation/gitcredentials.txt
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/git/Documentation/gitcredentials.txt')
-rw-r--r--third_party/git/Documentation/gitcredentials.txt298
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 758bf39ba385..000000000000
--- 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