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 currently 67includes the following helpers: 68 69cache:: 70 71 Cache credentials in memory for a short period of time. See 72 linkgit:git-credential-cache[1] for details. 73 74store:: 75 76 Store credentials indefinitely on disk. See 77 linkgit:git-credential-store[1] for details. 78 79You may also have third-party helpers installed; search for 80`credential-*` in the output of `git help -a`, and consult the 81documentation of individual helpers. Once you have selected a helper, 82you can tell Git to use it by putting its name into the 83credential.helper variable. 84 851. Find a helper. 86+ 87------------------------------------------- 88$ git help -a | grep credential- 89credential-foo 90------------------------------------------- 91 922. Read its description. 93+ 94------------------------------------------- 95$ git help credential-foo 96------------------------------------------- 97 983. Tell Git to use it. 99+ 100------------------------------------------- 101$ git config --global credential.helper foo 102------------------------------------------- 103 104 105CREDENTIAL CONTEXTS 106------------------- 107 108Git considers each credential to have a context defined by a URL. This context 109is used to look up context-specific configuration, and is passed to any 110helpers, which may use it as an index into secure storage. 111 112For instance, imagine we are accessing `https://example.com/foo.git`. When Git 113looks into a config file to see if a section matches this context, it will 114consider the two a match if the context is a more-specific subset of the 115pattern in the config file. For example, if you have this in your config file: 116 117-------------------------------------- 118[credential "https://example.com"] 119 username = foo 120-------------------------------------- 121 122then we will match: both protocols are the same, both hosts are the same, and 123the "pattern" URL does not care about the path component at all. However, this 124context would not match: 125 126-------------------------------------- 127[credential "https://kernel.org"] 128 username = foo 129-------------------------------------- 130 131because the hostnames differ. Nor would it match `foo.example.com`; Git 132compares hostnames exactly, without considering whether two hosts are part of 133the same domain. Likewise, a config entry for `http://example.com` would not 134match: Git compares the protocols exactly. 135 136 137CONFIGURATION OPTIONS 138--------------------- 139 140Options for a credential context can be configured either in 141`credential.*` (which applies to all credentials), or 142`credential.<url>.*`, where <url> matches the context as described 143above. 144 145The following options are available in either location: 146 147helper:: 148 149 The name of an external credential helper, and any associated options. 150 If the helper name is not an absolute path, then the string `git 151 credential-` is prepended. The resulting string is executed by the 152 shell (so, for example, setting this to `foo --option=bar` will execute 153 `git credential-foo --option=bar` via the shell. See the manual of 154 specific helpers for examples of their use. 155+ 156If there are multiple instances of the `credential.helper` configuration 157variable, each helper will be tried in turn, and may provide a username, 158password, or nothing. Once Git has acquired both a username and a 159password, no more helpers will be tried. 160+ 161If `credential.helper` is configured to the empty string, this resets 162the helper list to empty (so you may override a helper set by a 163lower-priority config file by configuring the empty-string helper, 164followed by whatever set of helpers you would like). 165 166username:: 167 168 A default username, if one is not provided in the URL. 169 170useHttpPath:: 171 172 By default, Git does not consider the "path" component of an http URL 173 to be worth matching via external helpers. This means that a credential 174 stored for `https://example.com/foo.git` will also be used for 175 `https://example.com/bar.git`. If you do want to distinguish these 176 cases, set this option to `true`. 177 178 179CUSTOM HELPERS 180-------------- 181 182You can write your own custom helpers to interface with any system in 183which you keep credentials. See the documentation for Git's 184link:technical/api-credentials.html[credentials API] for details. 185 186GIT 187--- 188Part of the linkgit:git[1] suite