Documentation/gitcredentials.txt

   1 gitcredentials(7)
   2 =================
   3
   4 NAME
   5 ----
   6 gitcredentials - providing usernames and passwords to git
   7
   8 SYNOPSIS
   9 --------
  10 ------------------
  11 git config credential.https:example.com.username myusername
  12 git config credential.helper "$helper $options"
  13 ------------------
  14
  15 DESCRIPTION
  16 -----------
  17
  18 Git will sometimes need credentials from the user in order to perform
  19 operations; for example, it may need to ask for a username and password
  20 in order to access a remote repository over HTTP. This manual describes
  21 the mechanisms git uses to request these credentials, as well as some
  22 features to avoid inputting these credentials repeatedly.
  23
  24 REQUESTING CREDENTIALS
  25 ----------------------
  26
  27 Without any credential helpers defined, git will try the following
  28 strategies to ask the user for usernames and passwords:
  29
  30 1. 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
  35 2. Otherwise, if the `core.askpass` configuration variable is set, its
  36    value is used as above.
  37
  38 3. Otherwise, if the `SSH_ASKPASS` environment variable is set, its
  39    value is used as above.
  40
  41 4. Otherwise, the user is prompted on the terminal.
  42
  43 AVOIDING REPETITION
  44 -------------------
  45
  46 It can be cumbersome to input the same credentials over and over.  Git
  47 provides two methods to reduce this annoyance:
  48
  49 1. Static configuration of usernames for a given authentication context.
  50
  51 2. Credential helpers to cache or store passwords, or to interact with
  52    a system password wallet or keychain.
  53
  54 STATIC CONFIGURATION
  55 --------------------
  56
  57 Git can look for credential information in your git config files. Note
  58 that it only makes sense to store usernames, not passwords, as git
  59 config files are not encrypted or usually even protected by filesystem
  60 permissions.
  61
  62 For a given credential request, git uses a unique token to represent the
  63 context of a request. For example, a request to
  64 `https://example.com/repo.git` would have the context
  65 `https:example.com`. See `CONTEXT TOKENS` below for a full list.
  66
  67 To statically configure a username, set the configuration variable
  68 `credential.$token.username`. For example, in this instance git will
  69 prompt only for the password, not the username:
  70
  71 --------------------------------------------------------------
  72 $ git config --global credential.https:example.com.username me
  73 $ git push https://example.com/repo.git
  74 Password:
  75 --------------------------------------------------------------
  76
  77 CREDENTIAL HELPERS
  78 ------------------
  79
  80 Credential helpers are external programs from which git can request
  81 usernames and passwords.
  82
  83 To use a helper, you must first select one to use. Git currently
  84 includes the following helpers:
  85
  86 cache::
  87
  88         Cache credentials in memory for a short period of time. See
  89         linkgit:git-credential-cache[1] for details.
  90
  91 store::
  92
  93         Store credentials indefinitely on disk. See
  94         linkgit:git-credential-store[1] for details.
  95
  96 You may may also have third-party helpers installed; search for
  97 `credential-*` in the output of `git help -a`, and consult the
  98 documentation of individual helpers.  Once you have selected a helper,
  99 you can tell git to use it by putting its name into the
 100 credential.helper variable.
 101
 102 1. Find a helper.
 103 +
 104 -------------------------------------------
 105 $ git help -a | grep credential-
 106 credential-foo
 107 -------------------------------------------
 108
 109 2. Read its description.
 110 +
 111 -------------------------------------------
 112 $ git help credential-foo
 113 -------------------------------------------
 114
 115 3. Tell git to use it.
 116 +
 117 -------------------------------------------
 118 $ git config --global credential.helper foo
 119 -------------------------------------------
 120
 121 If there are multiple instances of the `credential.helper` configuration
 122 variable, each helper will be tried in turn, and may provide a username,
 123 password, or nothing. Once git has acquired both a username and a
 124 password, no more helpers will be tried.
 125
 126 CUSTOM HELPERS
 127 --------------
 128
 129 You can write your own custom helpers to interface with any system in
 130 which you keep credentials. See the documentation for git's
 131 link:technical/api-credentials.html[credentials API] for details.
 132
 133 CONTEXT TOKENS
 134 --------------
 135
 136 The full set of unique context tokens provided by git to credential
 137 helpers is:
 138
 139 `$protocol:$hostname`::
 140
 141         A network request to a specific host. `$protocol` is
 142         either `http` or `https`, and `$hostname` is the hostname
 143         provided to git (which may not be fully qualified).
 144
 145 `cert:$filename`::
 146
 147         A password to decrypt a certificate on disk.
 148
 149 GIT
 150 ---
 151 Part of the linkgit:git[1] suite