logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

gitcredentials.7 (15364B)


  1. '\" t
  2. .\" Title: gitcredentials
  3. .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
  4. .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
  5. .\" Date: 2025-03-14
  6. .\" Manual: Git Manual
  7. .\" Source: Git 2.49.0
  8. .\" Language: English
  9. .\"
  10. .TH "GITCREDENTIALS" "7" "2025-03-14" "Git 2\&.49\&.0" "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. .SH "DESCRIPTION"
  39. .sp
  40. 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\&.
  41. .SH "REQUESTING CREDENTIALS"
  42. .sp
  43. Without any credential helpers defined, Git will try the following strategies to ask the user for usernames and passwords:
  44. .sp
  45. .RS 4
  46. .ie n \{\
  47. \h'-04' 1.\h'+01'\c
  48. .\}
  49. .el \{\
  50. .sp -1
  51. .IP " 1." 4.2
  52. .\}
  53. If the
  54. \fBGIT_ASKPASS\fR
  55. 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\&.
  56. .RE
  57. .sp
  58. .RS 4
  59. .ie n \{\
  60. \h'-04' 2.\h'+01'\c
  61. .\}
  62. .el \{\
  63. .sp -1
  64. .IP " 2." 4.2
  65. .\}
  66. Otherwise, if the
  67. \fBcore\&.askPass\fR
  68. configuration variable is set, its value is used as above\&.
  69. .RE
  70. .sp
  71. .RS 4
  72. .ie n \{\
  73. \h'-04' 3.\h'+01'\c
  74. .\}
  75. .el \{\
  76. .sp -1
  77. .IP " 3." 4.2
  78. .\}
  79. Otherwise, if the
  80. \fBSSH_ASKPASS\fR
  81. environment variable is set, its value is used as above\&.
  82. .RE
  83. .sp
  84. .RS 4
  85. .ie n \{\
  86. \h'-04' 4.\h'+01'\c
  87. .\}
  88. .el \{\
  89. .sp -1
  90. .IP " 4." 4.2
  91. .\}
  92. Otherwise, the user is prompted on the terminal\&.
  93. .RE
  94. .SH "AVOIDING REPETITION"
  95. .sp
  96. It can be cumbersome to input the same credentials over and over\&. Git provides two methods to reduce this annoyance:
  97. .sp
  98. .RS 4
  99. .ie n \{\
  100. \h'-04' 1.\h'+01'\c
  101. .\}
  102. .el \{\
  103. .sp -1
  104. .IP " 1." 4.2
  105. .\}
  106. Static configuration of usernames for a given authentication context\&.
  107. .RE
  108. .sp
  109. .RS 4
  110. .ie n \{\
  111. \h'-04' 2.\h'+01'\c
  112. .\}
  113. .el \{\
  114. .sp -1
  115. .IP " 2." 4.2
  116. .\}
  117. Credential helpers to cache or store passwords, or to interact with a system password wallet or keychain\&.
  118. .RE
  119. .sp
  120. 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:
  121. .sp
  122. .if n \{\
  123. .RS 4
  124. .\}
  125. .nf
  126. [credential "https://example\&.com"]
  127. username = me
  128. .fi
  129. .if n \{\
  130. .RE
  131. .\}
  132. .sp
  133. 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\&.
  134. .sp
  135. To use a helper, you must first select one to use (see below for a list)\&.
  136. .sp
  137. You may also have third\-party helpers installed; search for \fBcredential\-\fR* in the output of \fBgit\fR \fBhelp\fR \fB\-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\&.
  138. .sp
  139. .RS 4
  140. .ie n \{\
  141. \h'-04' 1.\h'+01'\c
  142. .\}
  143. .el \{\
  144. .sp -1
  145. .IP " 1." 4.2
  146. .\}
  147. Find a helper\&.
  148. .sp
  149. .if n \{\
  150. .RS 4
  151. .\}
  152. .nf
  153. $ git help \-a | grep credential\-
  154. credential\-foo
  155. .fi
  156. .if n \{\
  157. .RE
  158. .\}
  159. .RE
  160. .sp
  161. .RS 4
  162. .ie n \{\
  163. \h'-04' 2.\h'+01'\c
  164. .\}
  165. .el \{\
  166. .sp -1
  167. .IP " 2." 4.2
  168. .\}
  169. Read its description\&.
  170. .sp
  171. .if n \{\
  172. .RS 4
  173. .\}
  174. .nf
  175. $ git help credential\-foo
  176. .fi
  177. .if n \{\
  178. .RE
  179. .\}
  180. .RE
  181. .sp
  182. .RS 4
  183. .ie n \{\
  184. \h'-04' 3.\h'+01'\c
  185. .\}
  186. .el \{\
  187. .sp -1
  188. .IP " 3." 4.2
  189. .\}
  190. Tell Git to use it\&.
  191. .sp
  192. .if n \{\
  193. .RS 4
  194. .\}
  195. .nf
  196. $ git config \-\-global credential\&.helper foo
  197. .fi
  198. .if n \{\
  199. .RE
  200. .\}
  201. .RE
  202. .SS "Available helpers"
  203. .sp
  204. Git currently includes the following helpers:
  205. .PP
  206. cache
  207. .RS 4
  208. Cache credentials in memory for a short period of time\&. See
  209. \fBgit-credential-cache\fR(1)
  210. for details\&.
  211. .RE
  212. .PP
  213. store
  214. .RS 4
  215. Store credentials indefinitely on disk\&. See
  216. \fBgit-credential-store\fR(1)
  217. for details\&.
  218. .RE
  219. .sp
  220. Popular helpers with secure persistent storage include:
  221. .sp
  222. .RS 4
  223. .ie n \{\
  224. \h'-04'\(bu\h'+03'\c
  225. .\}
  226. .el \{\
  227. .sp -1
  228. .IP \(bu 2.3
  229. .\}
  230. git\-credential\-libsecret (Linux)
  231. .RE
  232. .sp
  233. .RS 4
  234. .ie n \{\
  235. \h'-04'\(bu\h'+03'\c
  236. .\}
  237. .el \{\
  238. .sp -1
  239. .IP \(bu 2.3
  240. .\}
  241. git\-credential\-osxkeychain (macOS)
  242. .RE
  243. .sp
  244. .RS 4
  245. .ie n \{\
  246. \h'-04'\(bu\h'+03'\c
  247. .\}
  248. .el \{\
  249. .sp -1
  250. .IP \(bu 2.3
  251. .\}
  252. git\-credential\-wincred (Windows)
  253. .RE
  254. .sp
  255. .RS 4
  256. .ie n \{\
  257. \h'-04'\(bu\h'+03'\c
  258. .\}
  259. .el \{\
  260. .sp -1
  261. .IP \(bu 2.3
  262. .\}
  263. \m[blue]\fBGit Credential Manager\fR\m[]\&\s-2\u[1]\d\s+2
  264. (cross platform, included in Git for Windows)
  265. .RE
  266. .sp
  267. The community maintains a comprehensive list of Git credential helpers at \m[blue]\fBhttps://git\-scm\&.com/doc/credential\-helpers\fR\m[]\&.
  268. .SS "OAuth"
  269. .sp
  270. 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\&.
  271. .sp
  272. Popular helpers with OAuth support include:
  273. .sp
  274. .RS 4
  275. .ie n \{\
  276. \h'-04'\(bu\h'+03'\c
  277. .\}
  278. .el \{\
  279. .sp -1
  280. .IP \(bu 2.3
  281. .\}
  282. \m[blue]\fBGit Credential Manager\fR\m[]\&\s-2\u[1]\d\s+2
  283. (cross platform, included in Git for Windows)
  284. .RE
  285. .sp
  286. .RS 4
  287. .ie n \{\
  288. \h'-04'\(bu\h'+03'\c
  289. .\}
  290. .el \{\
  291. .sp -1
  292. .IP \(bu 2.3
  293. .\}
  294. \m[blue]\fBgit\-credential\-oauth\fR\m[]\&\s-2\u[2]\d\s+2
  295. (cross platform, included in many Linux distributions)
  296. .RE
  297. .SH "CREDENTIAL CONTEXTS"
  298. .sp
  299. 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\&.
  300. .sp
  301. 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:
  302. .sp
  303. .if n \{\
  304. .RS 4
  305. .\}
  306. .nf
  307. [credential "https://example\&.com"]
  308. username = foo
  309. .fi
  310. .if n \{\
  311. .RE
  312. .\}
  313. .sp
  314. 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:
  315. .sp
  316. .if n \{\
  317. .RS 4
  318. .\}
  319. .nf
  320. [credential "https://kernel\&.org"]
  321. username = foo
  322. .fi
  323. .if n \{\
  324. .RE
  325. .\}
  326. .sp
  327. 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\&.\fR\fI<URL>\fR\&.* options\&.
  328. .sp
  329. 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\&.
  330. .SH "CONFIGURATION OPTIONS"
  331. .sp
  332. Options for a credential context can be configured either in \fBcredential\&.\fR* (which applies to all credentials), or \fBcredential\&.\fR\fI<URL>\fR\&.*, where <URL> matches the context as described above\&.
  333. .sp
  334. The following options are available in either location:
  335. .PP
  336. helper
  337. .RS 4
  338. The name of an external credential helper, and any associated options\&. If the helper name is not an absolute path, then the string
  339. \fBgit\fR
  340. \fBcredential\-\fR
  341. is prepended\&. The resulting string is executed by the shell (so, for example, setting this to
  342. \fBfoo\fR
  343. \fB\-\-option=bar\fR
  344. will execute
  345. \fBgit\fR
  346. \fBcredential\-foo\fR
  347. \fB\-\-option=bar\fR
  348. via the shell\&. See the manual of specific helpers for examples of their use\&.
  349. .sp
  350. If there are multiple instances of the
  351. \fBcredential\&.helper\fR
  352. 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\&.
  353. .sp
  354. If
  355. \fBcredential\&.helper\fR
  356. 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)\&.
  357. .RE
  358. .PP
  359. username
  360. .RS 4
  361. A default username, if one is not provided in the URL\&.
  362. .RE
  363. .PP
  364. useHttpPath
  365. .RS 4
  366. 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
  367. \fBhttps://example\&.com/foo\&.git\fR
  368. will also be used for
  369. \fBhttps://example\&.com/bar\&.git\fR\&. If you do want to distinguish these cases, set this option to
  370. \fBtrue\fR\&.
  371. .RE
  372. .SH "CUSTOM HELPERS"
  373. .sp
  374. You can write your own custom helpers to interface with any system in which you keep credentials\&.
  375. .sp
  376. 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)\&.
  377. .sp
  378. 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:
  379. .sp
  380. .RS 4
  381. .ie n \{\
  382. \h'-04' 1.\h'+01'\c
  383. .\}
  384. .el \{\
  385. .sp -1
  386. .IP " 1." 4.2
  387. .\}
  388. If the helper string begins with "!", it is considered a shell snippet, and everything after the "!" becomes the command\&.
  389. .RE
  390. .sp
  391. .RS 4
  392. .ie n \{\
  393. \h'-04' 2.\h'+01'\c
  394. .\}
  395. .el \{\
  396. .sp -1
  397. .IP " 2." 4.2
  398. .\}
  399. Otherwise, if the helper string begins with an absolute path, the verbatim helper string becomes the command\&.
  400. .RE
  401. .sp
  402. .RS 4
  403. .ie n \{\
  404. \h'-04' 3.\h'+01'\c
  405. .\}
  406. .el \{\
  407. .sp -1
  408. .IP " 3." 4.2
  409. .\}
  410. Otherwise, the string "git credential\-" is prepended to the helper string, and the result becomes the command\&.
  411. .RE
  412. .sp
  413. The resulting command then has an "operation" argument appended to it (see below for details), and the result is executed by the shell\&.
  414. .sp
  415. Here are some example specifications:
  416. .sp
  417. .if n \{\
  418. .RS 4
  419. .\}
  420. .nf
  421. # run "git credential\-foo"
  422. [credential]
  423. helper = foo
  424. # same as above, but pass an argument to the helper
  425. [credential]
  426. helper = "foo \-\-bar=baz"
  427. # the arguments are parsed by the shell, so use shell
  428. # quoting if necessary
  429. [credential]
  430. helper = "foo \-\-bar=\*(Aqwhitespace arg\*(Aq"
  431. # store helper (discouraged) with custom location for the db file;
  432. # use `\-\-file ~/\&.git\-secret\&.txt`, rather than `\-\-file=~/\&.git\-secret\&.txt`,
  433. # to allow the shell to expand tilde to the home directory\&.
  434. [credential]
  435. helper = "store \-\-file ~/\&.git\-secret\&.txt"
  436. # you can also use an absolute path, which will not use the git wrapper
  437. [credential]
  438. helper = "/path/to/my/helper \-\-with\-arguments"
  439. # or you can specify your own shell snippet
  440. [credential "https://example\&.com"]
  441. username = your_user
  442. helper = "!f() { test \e"$1\e" = get && echo \e"password=$(cat $HOME/\&.secret)\e"; }; f"
  443. .fi
  444. .if n \{\
  445. .RE
  446. .\}
  447. .sp
  448. 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\fR \fBconfig\fR \fBcredential\&.helper\fR \fB$NAME\fR\&.
  449. .sp
  450. When a helper is executed, it will have one "operation" argument appended to its command line, which is one of:
  451. .PP
  452. \fBget\fR
  453. .RS 4
  454. Return a matching credential, if any exists\&.
  455. .RE
  456. .PP
  457. \fBstore\fR
  458. .RS 4
  459. Store the credential, if applicable to the helper\&.
  460. .RE
  461. .PP
  462. \fBerase\fR
  463. .RS 4
  464. Remove matching credentials, if any, from the helper\(cqs storage\&.
  465. .RE
  466. .sp
  467. 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\fR \fBcredential\fR plumbing command (see the section \fBINPUT/OUTPUT\fR \fBFORMAT\fR in \fBgit-credential\fR(1) for a detailed specification)\&.
  468. .sp
  469. 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\&.
  470. .sp
  471. While it is possible to override all attributes, well behaving helpers should refrain from doing so for any attribute other than username and password\&.
  472. .sp
  473. 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)\&.
  474. .sp
  475. Similarly, no more helpers will be consulted once both username and password had been provided\&.
  476. .sp
  477. For a \fBstore\fR or \fBerase\fR operation, the helper\(cqs output is ignored\&.
  478. .sp
  479. If a helper fails to perform the requested operation or needs to notify the user of a potential issue, it may write to stderr\&.
  480. .sp
  481. If it does not support the requested operation (e\&.g\&., a read\-only store or generator), it should silently ignore the request\&.
  482. .sp
  483. 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)\&.
  484. .SH "GIT"
  485. .sp
  486. Part of the \fBgit\fR(1) suite
  487. .SH "NOTES"
  488. .IP " 1." 4
  489. Git Credential Manager
  490. .RS 4
  491. \%https://github.com/git-ecosystem/git-credential-manager
  492. .RE
  493. .IP " 2." 4
  494. git-credential-oauth
  495. .RS 4
  496. \%https://github.com/hickford/git-credential-oauth
  497. .RE