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: 2024-05-28
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.45.1.313.g3a57aa566a
   8 .\"  Language: English
   9 .\"
  10 .TH "GITCREDENTIALS" "7" "2024\-05\-28" "Git 2\&.45\&.1\&.313\&.g3a57aa" "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 .SS "Available helpers"
 222 .sp
 223 The community maintains a comprehensive list of Git credential helpers at \m[blue]\fBhttps://git\-scm\&.com/doc/credential\-helpers\fR\m[]\&.
 224 .SS "OAuth"
 225 .sp
 226 An alternative to inputting passwords or personal access tokens is to use an OAuth credential helper\&. Initial authentication opens a browser window to the host\&. Subsequent authentication happens in the background\&. Many popular Git hosts support OAuth\&.
 227 .SH "CREDENTIAL CONTEXTS"
 228 .sp
 229 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\&.
 230 .sp
 231 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:
 232 .sp
 233 .if n \{\
 234 .RS 4
 235 .\}
 236 .nf
 237 [credential "https://example\&.com"]
 238         username = foo
 239 .fi
 240 .if n \{\
 241 .RE
 242 .\}
 243 .sp
 244 .sp
 245 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:
 246 .sp
 247 .if n \{\
 248 .RS 4
 249 .\}
 250 .nf
 251 [credential "https://kernel\&.org"]
 252         username = foo
 253 .fi
 254 .if n \{\
 255 .RE
 256 .\}
 257 .sp
 258 .sp
 259 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\&.
 260 .sp
 261 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\&.
 262 .SH "CONFIGURATION OPTIONS"
 263 .sp
 264 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\&.
 265 .sp
 266 The following options are available in either location:
 267 .PP
 268 helper
 269 .RS 4
 270 The name of an external credential helper, and any associated options\&. If the helper name is not an absolute path, then the string
 271 \fBgit credential\-\fR
 272 is prepended\&. The resulting string is executed by the shell (so, for example, setting this to
 273 \fBfoo \-\-option=bar\fR
 274 will execute
 275 \fBgit credential\-foo \-\-option=bar\fR
 276 via the shell\&. See the manual of specific helpers for examples of their use\&.
 277 .sp
 278 If there are multiple instances of the
 279 \fBcredential\&.helper\fR
 280 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\&.
 281 .sp
 282 If
 283 \fBcredential\&.helper\fR
 284 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)\&.
 285 .RE
 286 .PP
 287 username
 288 .RS 4
 289 A default username, if one is not provided in the URL\&.
 290 .RE
 291 .PP
 292 useHttpPath
 293 .RS 4
 294 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
 295 \fBhttps://example\&.com/foo\&.git\fR
 296 will also be used for
 297 \fBhttps://example\&.com/bar\&.git\fR\&. If you do want to distinguish these cases, set this option to
 298 \fBtrue\fR\&.
 299 .RE
 300 .SH "CUSTOM HELPERS"
 301 .sp
 302 You can write your own custom helpers to interface with any system in which you keep credentials\&.
 303 .sp
 304 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)\&.
 305 .sp
 306 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:
 307 .sp
 308 .RS 4
 309 .ie n \{\
 310 \h'-04' 1.\h'+01'\c
 311 .\}
 312 .el \{\
 313 .sp -1
 314 .IP "  1." 4.2
 315 .\}
 316 If the helper string begins with "!", it is considered a shell snippet, and everything after the "!" becomes the command\&.
 317 .RE
 318 .sp
 319 .RS 4
 320 .ie n \{\
 321 \h'-04' 2.\h'+01'\c
 322 .\}
 323 .el \{\
 324 .sp -1
 325 .IP "  2." 4.2
 326 .\}
 327 Otherwise, if the helper string begins with an absolute path, the verbatim helper string becomes the command\&.
 328 .RE
 329 .sp
 330 .RS 4
 331 .ie n \{\
 332 \h'-04' 3.\h'+01'\c
 333 .\}
 334 .el \{\
 335 .sp -1
 336 .IP "  3." 4.2
 337 .\}
 338 Otherwise, the string "git credential\-" is prepended to the helper string, and the result becomes the command\&.
 339 .RE
 340 .sp
 341 The resulting command then has an "operation" argument appended to it (see below for details), and the result is executed by the shell\&.
 342 .sp
 343 Here are some example specifications:
 344 .sp
 345 .if n \{\
 346 .RS 4
 347 .\}
 348 .nf
 349 # run "git credential\-foo"
 350 [credential]
 351         helper = foo
 352
 353 # same as above, but pass an argument to the helper
 354 [credential]
 355         helper = "foo \-\-bar=baz"
 356
 357 # the arguments are parsed by the shell, so use shell
 358 # quoting if necessary
 359 [credential]
 360         helper = "foo \-\-bar=\*(Aqwhitespace arg\*(Aq"
 361
 362 # you can also use an absolute path, which will not use the git wrapper
 363 [credential]
 364         helper = "/path/to/my/helper \-\-with\-arguments"
 365
 366 # or you can specify your own shell snippet
 367 [credential "https://example\&.com"]
 368         username = your_user
 369         helper = "!f() { test \e"$1\e" = get && echo \e"password=$(cat $HOME/\&.secret)\e"; }; f"
 370 .fi
 371 .if n \{\
 372 .RE
 373 .\}
 374 .sp
 375 .sp
 376 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\&.
 377 .sp
 378 When a helper is executed, it will have one "operation" argument appended to its command line, which is one of:
 379 .PP
 380 \fBget\fR
 381 .RS 4
 382 Return a matching credential, if any exists\&.
 383 .RE
 384 .PP
 385 \fBstore\fR
 386 .RS 4
 387 Store the credential, if applicable to the helper\&.
 388 .RE
 389 .PP
 390 \fBerase\fR
 391 .RS 4
 392 Remove matching credentials, if any, from the helper\(cqs storage\&.
 393 .RE
 394 .sp
 395 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)\&.
 396 .sp
 397 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\&.
 398 .sp
 399 While it is possible to override all attributes, well behaving helpers should refrain from doing so for any attribute other than username and password\&.
 400 .sp
 401 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)\&.
 402 .sp
 403 Similarly, no more helpers will be consulted once both username and password had been provided\&.
 404 .sp
 405 For a \fBstore\fR or \fBerase\fR operation, the helper\(cqs output is ignored\&.
 406 .sp
 407 If a helper fails to perform the requested operation or needs to notify the user of a potential issue, it may write to stderr\&.
 408 .sp
 409 If it does not support the requested operation (e\&.g\&., a read\-only store or generator), it should silently ignore the request\&.
 410 .sp
 411 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)\&.
 412 .SH "GIT"
 413 .sp
 414 Part of the \fBgit\fR(1) suite