man7/gitcredentials.7

   1 '\" t
   2 .\"     Title: gitcredentials
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2023-05-17
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.41.0.rc0.4.g004e0f790f
   8 .\"  Language: English
   9 .\"
  10 .TH "GITCREDENTIALS" "7" "2023\-05\-17" "Git 2\&.41\&.0\&.rc0\&.4\&.g00" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 gitcredentials \- Providing usernames and passwords to Git
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 git config credential\&.https://example\&.com\&.username myusername
  36 git config credential\&.helper "$helper $options"
  37 .fi
  38 .sp
  39 .SH "DESCRIPTION"
  40 .sp
  41 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\&. Some remotes accept a personal access token or OAuth access token as a password\&. This manual describes the mechanisms Git uses to request these credentials, as well as some features to avoid inputting these credentials repeatedly\&.
  42 .SH "REQUESTING CREDENTIALS"
  43 .sp
  44 Without any credential helpers defined, Git will try the following strategies to ask the user for usernames and passwords:
  45 .sp
  46 .RS 4
  47 .ie n \{\
  48 \h'-04' 1.\h'+01'\c
  49 .\}
  50 .el \{\
  51 .sp -1
  52 .IP "  1." 4.2
  53 .\}
  54 If the
  55 \fBGIT_ASKPASS\fR
  56 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\(cqs input is read from its standard output\&.
  57 .RE
  58 .sp
  59 .RS 4
  60 .ie n \{\
  61 \h'-04' 2.\h'+01'\c
  62 .\}
  63 .el \{\
  64 .sp -1
  65 .IP "  2." 4.2
  66 .\}
  67 Otherwise, if the
  68 \fBcore\&.askPass\fR
  69 configuration variable is set, its value is used as above\&.
  70 .RE
  71 .sp
  72 .RS 4
  73 .ie n \{\
  74 \h'-04' 3.\h'+01'\c
  75 .\}
  76 .el \{\
  77 .sp -1
  78 .IP "  3." 4.2
  79 .\}
  80 Otherwise, if the
  81 \fBSSH_ASKPASS\fR
  82 environment variable is set, its value is used as above\&.
  83 .RE
  84 .sp
  85 .RS 4
  86 .ie n \{\
  87 \h'-04' 4.\h'+01'\c
  88 .\}
  89 .el \{\
  90 .sp -1
  91 .IP "  4." 4.2
  92 .\}
  93 Otherwise, the user is prompted on the terminal\&.
  94 .RE
  95 .SH "AVOIDING REPETITION"
  96 .sp
  97 It can be cumbersome to input the same credentials over and over\&. Git provides two methods to reduce this annoyance:
  98 .sp
  99 .RS 4
 100 .ie n \{\
 101 \h'-04' 1.\h'+01'\c
 102 .\}
 103 .el \{\
 104 .sp -1
 105 .IP "  1." 4.2
 106 .\}
 107 Static configuration of usernames for a given authentication context\&.
 108 .RE
 109 .sp
 110 .RS 4
 111 .ie n \{\
 112 \h'-04' 2.\h'+01'\c
 113 .\}
 114 .el \{\
 115 .sp -1
 116 .IP "  2." 4.2
 117 .\}
 118 Credential helpers to cache or store passwords, or to interact with a system password wallet or keychain\&.
 119 .RE
 120 .sp
 121 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:
 122 .sp
 123 .if n \{\
 124 .RS 4
 125 .\}
 126 .nf
 127 [credential "https://example\&.com"]
 128         username = me
 129 .fi
 130 .if n \{\
 131 .RE
 132 .\}
 133 .sp
 134 .sp
 135 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\&. Alternatively, a credential\-generating helper might generate credentials for certain servers via some API\&.
 136 .sp
 137 To use a helper, you must first select one to use\&. Git currently includes the following helpers:
 138 .PP
 139 cache
 140 .RS 4
 141 Cache credentials in memory for a short period of time\&. See
 142 \fBgit-credential-cache\fR(1)
 143 for details\&.
 144 .RE
 145 .PP
 146 store
 147 .RS 4
 148 Store credentials indefinitely on disk\&. See
 149 \fBgit-credential-store\fR(1)
 150 for details\&.
 151 .RE
 152 .sp
 153 You may also have third\-party helpers installed; search for \fBcredential\-*\fR in the output of \fBgit help \-a\fR, 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\&.
 154 .sp
 155 .RS 4
 156 .ie n \{\
 157 \h'-04' 1.\h'+01'\c
 158 .\}
 159 .el \{\
 160 .sp -1
 161 .IP "  1." 4.2
 162 .\}
 163 Find a helper\&.
 164 .sp
 165 .if n \{\
 166 .RS 4
 167 .\}
 168 .nf
 169 $ git help \-a | grep credential\-
 170 credential\-foo
 171 .fi
 172 .if n \{\
 173 .RE
 174 .\}
 175 .sp
 176 .RE
 177 .sp
 178 .RS 4
 179 .ie n \{\
 180 \h'-04' 2.\h'+01'\c
 181 .\}
 182 .el \{\
 183 .sp -1
 184 .IP "  2." 4.2
 185 .\}
 186 Read its description\&.
 187 .sp
 188 .if n \{\
 189 .RS 4
 190 .\}
 191 .nf
 192 $ git help credential\-foo
 193 .fi
 194 .if n \{\
 195 .RE
 196 .\}
 197 .sp
 198 .RE
 199 .sp
 200 .RS 4
 201 .ie n \{\
 202 \h'-04' 3.\h'+01'\c
 203 .\}
 204 .el \{\
 205 .sp -1
 206 .IP "  3." 4.2
 207 .\}
 208 Tell Git to use it\&.
 209 .sp
 210 .if n \{\
 211 .RS 4
 212 .\}
 213 .nf
 214 $ git config \-\-global credential\&.helper foo
 215 .fi
 216 .if n \{\
 217 .RE
 218 .\}
 219 .sp
 220 .RE
 221 .SH "CREDENTIAL CONTEXTS"
 222 .sp
 223 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\&.
 224 .sp
 225 For instance, imagine we are accessing \fBhttps://example\&.com/foo\&.git\fR\&. 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:
 226 .sp
 227 .if n \{\
 228 .RS 4
 229 .\}
 230 .nf
 231 [credential "https://example\&.com"]
 232         username = foo
 233 .fi
 234 .if n \{\
 235 .RE
 236 .\}
 237 .sp
 238 .sp
 239 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:
 240 .sp
 241 .if n \{\
 242 .RS 4
 243 .\}
 244 .nf
 245 [credential "https://kernel\&.org"]
 246         username = foo
 247 .fi
 248 .if n \{\
 249 .RE
 250 .\}
 251 .sp
 252 .sp
 253 because the hostnames differ\&. Nor would it match \fBfoo\&.example\&.com\fR; Git compares hostnames exactly, without considering whether two hosts are part of the same domain\&. Likewise, a config entry for \fBhttp://example\&.com\fR 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 \fBhttp\&.<URL>\&.*\fR options\&.
 254 .sp
 255 If the "pattern" URL does include a path component, then this too must match exactly: the context \fBhttps://example\&.com/bar/baz\&.git\fR will match a config entry for \fBhttps://example\&.com/bar/baz\&.git\fR (in addition to matching the config entry for \fBhttps://example\&.com\fR) but will not match a config entry for \fBhttps://example\&.com/bar\fR\&.
 256 .SH "CONFIGURATION OPTIONS"
 257 .sp
 258 Options for a credential context can be configured either in \fBcredential\&.*\fR (which applies to all credentials), or \fBcredential\&.<URL>\&.*\fR, where <URL> matches the context as described above\&.
 259 .sp
 260 The following options are available in either location:
 261 .PP
 262 helper
 263 .RS 4
 264 The name of an external credential helper, and any associated options\&. If the helper name is not an absolute path, then the string
 265 \fBgit credential\-\fR
 266 is prepended\&. The resulting string is executed by the shell (so, for example, setting this to
 267 \fBfoo \-\-option=bar\fR
 268 will execute
 269 \fBgit credential\-foo \-\-option=bar\fR
 270 via the shell\&. See the manual of specific helpers for examples of their use\&.
 271 .sp
 272 If there are multiple instances of the
 273 \fBcredential\&.helper\fR
 274 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 non\-expired password, no more helpers will be tried\&.
 275 .sp
 276 If
 277 \fBcredential\&.helper\fR
 278 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)\&.
 279 .RE
 280 .PP
 281 username
 282 .RS 4
 283 A default username, if one is not provided in the URL\&.
 284 .RE
 285 .PP
 286 useHttpPath
 287 .RS 4
 288 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
 289 \fBhttps://example\&.com/foo\&.git\fR
 290 will also be used for
 291 \fBhttps://example\&.com/bar\&.git\fR\&. If you do want to distinguish these cases, set this option to
 292 \fBtrue\fR\&.
 293 .RE
 294 .SH "CUSTOM HELPERS"
 295 .sp
 296 You can write your own custom helpers to interface with any system in which you keep credentials\&.
 297 .sp
 298 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)\&.
 299 .sp
 300 Each helper is specified by a single string in the configuration variable \fBcredential\&.helper\fR (and others, see \fBgit-config\fR(1))\&. The string is transformed by Git into a command to be executed using these rules:
 301 .sp
 302 .RS 4
 303 .ie n \{\
 304 \h'-04' 1.\h'+01'\c
 305 .\}
 306 .el \{\
 307 .sp -1
 308 .IP "  1." 4.2
 309 .\}
 310 If the helper string begins with "!", it is considered a shell snippet, and everything after the "!" becomes the command\&.
 311 .RE
 312 .sp
 313 .RS 4
 314 .ie n \{\
 315 \h'-04' 2.\h'+01'\c
 316 .\}
 317 .el \{\
 318 .sp -1
 319 .IP "  2." 4.2
 320 .\}
 321 Otherwise, if the helper string begins with an absolute path, the verbatim helper string becomes the command\&.
 322 .RE
 323 .sp
 324 .RS 4
 325 .ie n \{\
 326 \h'-04' 3.\h'+01'\c
 327 .\}
 328 .el \{\
 329 .sp -1
 330 .IP "  3." 4.2
 331 .\}
 332 Otherwise, the string "git credential\-" is prepended to the helper string, and the result becomes the command\&.
 333 .RE
 334 .sp
 335 The resulting command then has an "operation" argument appended to it (see below for details), and the result is executed by the shell\&.
 336 .sp
 337 Here are some example specifications:
 338 .sp
 339 .if n \{\
 340 .RS 4
 341 .\}
 342 .nf
 343 # run "git credential\-foo"
 344 [credential]
 345         helper = foo
 346
 347 # same as above, but pass an argument to the helper
 348 [credential]
 349         helper = "foo \-\-bar=baz"
 350
 351 # the arguments are parsed by the shell, so use shell
 352 # quoting if necessary
 353 [credential]
 354         helper = "foo \-\-bar=\*(Aqwhitespace arg\*(Aq"
 355
 356 # you can also use an absolute path, which will not use the git wrapper
 357 [credential]
 358         helper = "/path/to/my/helper \-\-with\-arguments"
 359
 360 # or you can specify your own shell snippet
 361 [credential "https://example\&.com"]
 362         username = your_user
 363         helper = "!f() { test \e"$1\e" = get && echo \e"password=$(cat $HOME/\&.secret)\e"; }; f"
 364 .fi
 365 .if n \{\
 366 .RE
 367 .\}
 368 .sp
 369 .sp
 370 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 \fB$PATH\fR or \fB$GIT_EXEC_PATH\fR during installation, which will allow a user to enable it with \fBgit config credential\&.helper $NAME\fR\&.
 371 .sp
 372 When a helper is executed, it will have one "operation" argument appended to its command line, which is one of:
 373 .PP
 374 \fBget\fR
 375 .RS 4
 376 Return a matching credential, if any exists\&.
 377 .RE
 378 .PP
 379 \fBstore\fR
 380 .RS 4
 381 Store the credential, if applicable to the helper\&.
 382 .RE
 383 .PP
 384 \fBerase\fR
 385 .RS 4
 386 Remove a matching credential, if any, from the helper\(cqs storage\&.
 387 .RE
 388 .sp
 389 The details of the credential will be provided on the helper\(cqs stdin stream\&. The exact format is the same as the input/output format of the \fBgit credential\fR plumbing command (see the section \fBINPUT/OUTPUT FORMAT\fR in \fBgit-credential\fR(1) for a detailed specification)\&.
 390 .sp
 391 For a \fBget\fR operation, the helper should produce a list of attributes on stdout in the same format (see \fBgit-credential\fR(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\(cqs credential subsystem\&. Unrecognised attributes are silently discarded\&.
 392 .sp
 393 While it is possible to override all attributes, well behaving helpers should refrain from doing so for any attribute other than username and password\&.
 394 .sp
 395 If a helper outputs a \fBquit\fR attribute with a value of \fBtrue\fR or \fB1\fR, no further helpers will be consulted, nor will the user be prompted (if no credential has been provided, the operation will then fail)\&.
 396 .sp
 397 Similarly, no more helpers will be consulted once both username and password had been provided\&.
 398 .sp
 399 For a \fBstore\fR or \fBerase\fR operation, the helper\(cqs output is ignored\&.
 400 .sp
 401 If a helper fails to perform the requested operation or needs to notify the user of a potential issue, it may write to stderr\&.
 402 .sp
 403 If it does not support the requested operation (e\&.g\&., a read\-only store or generator), it should silently ignore the request\&.
 404 .sp
 405 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)\&.
 406 .SH "GIT"
 407 .sp
 408 Part of the \fBgit\fR(1) suite