1gitcredentials(7) 2================= 3 4NAME 5---- 6gitcredentials - providing usernames and passwords to git 7 8SYNOPSIS 9-------- 10------------------ 11git config credential.https://example.com.username myusername 12git config credential.helper "$helper $options" 13------------------ 14 15DESCRIPTION 16----------- 17 18Git will sometimes need credentials from the user in order to perform 19operations; for example, it may need to ask for a username and password 20in order to access a remote repository over HTTP. This manual describes 21the mechanisms git uses to request these credentials, as well as some 22features to avoid inputting these credentials repeatedly. 23 24REQUESTING CREDENTIALS 25---------------------- 26 27Without any credential helpers defined, git will try the following 28strategies to ask the user for usernames and passwords: 29 301. If the `GIT_ASKPASS` environment variable is set, the program 31 specified by the variable is invoked. A suitable prompt is provided 32 to the program on the command line, and the user's input is read 33 from its standard output. 34 352. Otherwise, if the `core.askpass` configuration variable is set, its 36 value is used as above. 37 383. Otherwise, if the `SSH_ASKPASS` environment variable is set, its 39 value is used as above. 40 414. Otherwise, the user is prompted on the terminal. 42 43AVOIDING REPETITION 44------------------- 45 46It can be cumbersome to input the same credentials over and over. Git 47provides two methods to reduce this annoyance: 48 491. Static configuration of usernames for a given authentication context. 50 512. Credential helpers to cache or store passwords, or to interact with 52 a system password wallet or keychain. 53 54The first is simple and appropriate if you do not have secure storage available 55for a password. It is generally configured by adding this to your config: 56 57--------------------------------------- 58[credential "https://example.com"] 59 username = me 60--------------------------------------- 61 62Credential helpers, on the other hand, are external programs from which git can 63request both usernames and passwords; they typically interface with secure 64storage provided by the OS or other programs. 65 66To use a helper, you must first select one to use. Git does not yet 67include any credential helpers, but you may have third-party helpers 68installed; search for `credential-*` in the output of `git help -a`, and 69consult the documentation of individual helpers. Once you have selected 70a helper, you can tell git to use it by putting its name into the 71credential.helper variable. 72 731. Find a helper. 74+ 75------------------------------------------- 76$ git help -a | grep credential- 77credential-foo 78------------------------------------------- 79 802. Read its description. 81+ 82------------------------------------------- 83$ git help credential-foo 84------------------------------------------- 85 863. Tell git to use it. 87+ 88------------------------------------------- 89$ git config --global credential.helper foo 90------------------------------------------- 91 92If there are multiple instances of the `credential.helper` configuration 93variable, each helper will be tried in turn, and may provide a username, 94password, or nothing. Once git has acquired both a username and a 95password, no more helpers will be tried. 96 97 98CREDENTIAL CONTEXTS 99------------------- 100 101Git considers each credential to have a context defined by a URL. This context 102is used to look up context-specific configuration, and is passed to any 103helpers, which may use it as an index into secure storage. 104 105For instance, imagine we are accessing `https://example.com/foo.git`. When git 106looks into a config file to see if a section matches this context, it will 107consider the two a match if the context is a more-specific subset of the 108pattern in the config file. For example, if you have this in your config file: 109 110-------------------------------------- 111[credential "https://example.com"] 112 username = foo 113-------------------------------------- 114 115then we will match: both protocols are the same, both hosts are the same, and 116the "pattern" URL does not care about the path component at all. However, this 117context would not match: 118 119-------------------------------------- 120[credential "https://kernel.org"] 121 username = foo 122-------------------------------------- 123 124because the hostnames differ. Nor would it match `foo.example.com`; git 125compares hostnames exactly, without considering whether two hosts are part of 126the same domain. Likewise, a config entry for `http://example.com` would not 127match: git compares the protocols exactly. 128 129 130CONFIGURATION OPTIONS 131--------------------- 132 133Options for a credential context can be configured either in 134`credential.\*` (which applies to all credentials), or 135`credential.<url>.\*`, where <url> matches the context as described 136above. 137 138The following options are available in either location: 139 140helper:: 141 142 The name of an external credential helper, and any associated options. 143 If the helper name is not an absolute path, then the string `git 144 credential-` is prepended. The resulting string is executed by the 145 shell (so, for example, setting this to `foo --option=bar` will execute 146 `git credential-foo --option=bar` via the shell. See the manual of 147 specific helpers for examples of their use. 148 149username:: 150 151 A default username, if one is not provided in the URL. 152 153useHttpPath:: 154 155 By default, git does not consider the "path" component of an http URL 156 to be worth matching via external helpers. This means that a credential 157 stored for `https://example.com/foo.git` will also be used for 158 `https://example.com/bar.git`. If you do want to distinguish these 159 cases, set this option to `true`. 160 161 162CUSTOM HELPERS 163-------------- 164 165You can write your own custom helpers to interface with any system in 166which you keep credentials. See the documentation for git's 167link:technical/api-credentials.html[credentials API] for details. 168 169GIT 170--- 171Part of the linkgit:git[1] suite