gitcredentials.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   3     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   4 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   5 <head>
   6 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
   7 <meta name="generator" content="AsciiDoc 10.2.0" />
   8 <title>gitcredentials(7)</title>
   9 <style type="text/css">
  10 /* Shared CSS for AsciiDoc xhtml11 and html5 backends */
  11
  12 /* Default font. */
  13 body {
  14   font-family: Georgia,serif;
  15 }
  16
  17 /* Title font. */
  18 h1, h2, h3, h4, h5, h6,
  19 div.title, caption.title,
  20 thead, p.table.header,
  21 #toctitle,
  22 #author, #revnumber, #revdate, #revremark,
  23 #footer {
  24   font-family: Arial,Helvetica,sans-serif;
  25 }
  26
  27 body {
  28   margin: 1em 5% 1em 5%;
  29 }
  30
  31 a {
  32   color: blue;
  33   text-decoration: underline;
  34 }
  35 a:visited {
  36   color: fuchsia;
  37 }
  38
  39 em {
  40   font-style: italic;
  41   color: navy;
  42 }
  43
  44 strong {
  45   font-weight: bold;
  46   color: #083194;
  47 }
  48
  49 h1, h2, h3, h4, h5, h6 {
  50   color: #527bbd;
  51   margin-top: 1.2em;
  52   margin-bottom: 0.5em;
  53   line-height: 1.3;
  54 }
  55
  56 h1, h2, h3 {
  57   border-bottom: 2px solid silver;
  58 }
  59 h2 {
  60   padding-top: 0.5em;
  61 }
  62 h3 {
  63   float: left;
  64 }
  65 h3 + * {
  66   clear: left;
  67 }
  68 h5 {
  69   font-size: 1.0em;
  70 }
  71
  72 div.sectionbody {
  73   margin-left: 0;
  74 }
  75
  76 hr {
  77   border: 1px solid silver;
  78 }
  79
  80 p {
  81   margin-top: 0.5em;
  82   margin-bottom: 0.5em;
  83 }
  84
  85 ul, ol, li > p {
  86   margin-top: 0;
  87 }
  88 ul > li     { color: #aaa; }
  89 ul > li > * { color: black; }
  90
  91 .monospaced, code, pre {
  92   font-family: "Courier New", Courier, monospace;
  93   font-size: inherit;
  94   color: navy;
  95   padding: 0;
  96   margin: 0;
  97 }
  98 pre {
  99   white-space: pre-wrap;
 100 }
 101
 102 #author {
 103   color: #527bbd;
 104   font-weight: bold;
 105   font-size: 1.1em;
 106 }
 107 #email {
 108 }
 109 #revnumber, #revdate, #revremark {
 110 }
 111
 112 #footer {
 113   font-size: small;
 114   border-top: 2px solid silver;
 115   padding-top: 0.5em;
 116   margin-top: 4.0em;
 117 }
 118 #footer-text {
 119   float: left;
 120   padding-bottom: 0.5em;
 121 }
 122 #footer-badges {
 123   float: right;
 124   padding-bottom: 0.5em;
 125 }
 126
 127 #preamble {
 128   margin-top: 1.5em;
 129   margin-bottom: 1.5em;
 130 }
 131 div.imageblock, div.exampleblock, div.verseblock,
 132 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 133 div.admonitionblock {
 134   margin-top: 1.0em;
 135   margin-bottom: 1.5em;
 136 }
 137 div.admonitionblock {
 138   margin-top: 2.0em;
 139   margin-bottom: 2.0em;
 140   margin-right: 10%;
 141   color: #606060;
 142 }
 143
 144 div.content { /* Block element content. */
 145   padding: 0;
 146 }
 147
 148 /* Block element titles. */
 149 div.title, caption.title {
 150   color: #527bbd;
 151   font-weight: bold;
 152   text-align: left;
 153   margin-top: 1.0em;
 154   margin-bottom: 0.5em;
 155 }
 156 div.title + * {
 157   margin-top: 0;
 158 }
 159
 160 td div.title:first-child {
 161   margin-top: 0.0em;
 162 }
 163 div.content div.title:first-child {
 164   margin-top: 0.0em;
 165 }
 166 div.content + div.title {
 167   margin-top: 0.0em;
 168 }
 169
 170 div.sidebarblock > div.content {
 171   background: #ffffee;
 172   border: 1px solid #dddddd;
 173   border-left: 4px solid #f0f0f0;
 174   padding: 0.5em;
 175 }
 176
 177 div.listingblock > div.content {
 178   border: 1px solid #dddddd;
 179   border-left: 5px solid #f0f0f0;
 180   background: #f8f8f8;
 181   padding: 0.5em;
 182 }
 183
 184 div.quoteblock, div.verseblock {
 185   padding-left: 1.0em;
 186   margin-left: 1.0em;
 187   margin-right: 10%;
 188   border-left: 5px solid #f0f0f0;
 189   color: #888;
 190 }
 191
 192 div.quoteblock > div.attribution {
 193   padding-top: 0.5em;
 194   text-align: right;
 195 }
 196
 197 div.verseblock > pre.content {
 198   font-family: inherit;
 199   font-size: inherit;
 200 }
 201 div.verseblock > div.attribution {
 202   padding-top: 0.75em;
 203   text-align: left;
 204 }
 205 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
 206 div.verseblock + div.attribution {
 207   text-align: left;
 208 }
 209
 210 div.admonitionblock .icon {
 211   vertical-align: top;
 212   font-size: 1.1em;
 213   font-weight: bold;
 214   text-decoration: underline;
 215   color: #527bbd;
 216   padding-right: 0.5em;
 217 }
 218 div.admonitionblock td.content {
 219   padding-left: 0.5em;
 220   border-left: 3px solid #dddddd;
 221 }
 222
 223 div.exampleblock > div.content {
 224   border-left: 3px solid #dddddd;
 225   padding-left: 0.5em;
 226 }
 227
 228 div.imageblock div.content { padding-left: 0; }
 229 span.image img { border-style: none; vertical-align: text-bottom; }
 230 a.image:visited { color: white; }
 231
 232 dl {
 233   margin-top: 0.8em;
 234   margin-bottom: 0.8em;
 235 }
 236 dt {
 237   margin-top: 0.5em;
 238   margin-bottom: 0;
 239   font-style: normal;
 240   color: navy;
 241 }
 242 dd > *:first-child {
 243   margin-top: 0.1em;
 244 }
 245
 246 ul, ol {
 247     list-style-position: outside;
 248 }
 249 ol.arabic {
 250   list-style-type: decimal;
 251 }
 252 ol.loweralpha {
 253   list-style-type: lower-alpha;
 254 }
 255 ol.upperalpha {
 256   list-style-type: upper-alpha;
 257 }
 258 ol.lowerroman {
 259   list-style-type: lower-roman;
 260 }
 261 ol.upperroman {
 262   list-style-type: upper-roman;
 263 }
 264
 265 div.compact ul, div.compact ol,
 266 div.compact p, div.compact p,
 267 div.compact div, div.compact div {
 268   margin-top: 0.1em;
 269   margin-bottom: 0.1em;
 270 }
 271
 272 tfoot {
 273   font-weight: bold;
 274 }
 275 td > div.verse {
 276   white-space: pre;
 277 }
 278
 279 div.hdlist {
 280   margin-top: 0.8em;
 281   margin-bottom: 0.8em;
 282 }
 283 div.hdlist tr {
 284   padding-bottom: 15px;
 285 }
 286 dt.hdlist1.strong, td.hdlist1.strong {
 287   font-weight: bold;
 288 }
 289 td.hdlist1 {
 290   vertical-align: top;
 291   font-style: normal;
 292   padding-right: 0.8em;
 293   color: navy;
 294 }
 295 td.hdlist2 {
 296   vertical-align: top;
 297 }
 298 div.hdlist.compact tr {
 299   margin: 0;
 300   padding-bottom: 0;
 301 }
 302
 303 .comment {
 304   background: yellow;
 305 }
 306
 307 .footnote, .footnoteref {
 308   font-size: 0.8em;
 309 }
 310
 311 span.footnote, span.footnoteref {
 312   vertical-align: super;
 313 }
 314
 315 #footnotes {
 316   margin: 20px 0 20px 0;
 317   padding: 7px 0 0 0;
 318 }
 319
 320 #footnotes div.footnote {
 321   margin: 0 0 5px 0;
 322 }
 323
 324 #footnotes hr {
 325   border: none;
 326   border-top: 1px solid silver;
 327   height: 1px;
 328   text-align: left;
 329   margin-left: 0;
 330   width: 20%;
 331   min-width: 100px;
 332 }
 333
 334 div.colist td {
 335   padding-right: 0.5em;
 336   padding-bottom: 0.3em;
 337   vertical-align: top;
 338 }
 339 div.colist td img {
 340   margin-top: 0.3em;
 341 }
 342
 343 @media print {
 344   #footer-badges { display: none; }
 345 }
 346
 347 #toc {
 348   margin-bottom: 2.5em;
 349 }
 350
 351 #toctitle {
 352   color: #527bbd;
 353   font-size: 1.1em;
 354   font-weight: bold;
 355   margin-top: 1.0em;
 356   margin-bottom: 0.1em;
 357 }
 358
 359 div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 360   margin-top: 0;
 361   margin-bottom: 0;
 362 }
 363 div.toclevel2 {
 364   margin-left: 2em;
 365   font-size: 0.9em;
 366 }
 367 div.toclevel3 {
 368   margin-left: 4em;
 369   font-size: 0.9em;
 370 }
 371 div.toclevel4 {
 372   margin-left: 6em;
 373   font-size: 0.9em;
 374 }
 375
 376 span.aqua { color: aqua; }
 377 span.black { color: black; }
 378 span.blue { color: blue; }
 379 span.fuchsia { color: fuchsia; }
 380 span.gray { color: gray; }
 381 span.green { color: green; }
 382 span.lime { color: lime; }
 383 span.maroon { color: maroon; }
 384 span.navy { color: navy; }
 385 span.olive { color: olive; }
 386 span.purple { color: purple; }
 387 span.red { color: red; }
 388 span.silver { color: silver; }
 389 span.teal { color: teal; }
 390 span.white { color: white; }
 391 span.yellow { color: yellow; }
 392
 393 span.aqua-background { background: aqua; }
 394 span.black-background { background: black; }
 395 span.blue-background { background: blue; }
 396 span.fuchsia-background { background: fuchsia; }
 397 span.gray-background { background: gray; }
 398 span.green-background { background: green; }
 399 span.lime-background { background: lime; }
 400 span.maroon-background { background: maroon; }
 401 span.navy-background { background: navy; }
 402 span.olive-background { background: olive; }
 403 span.purple-background { background: purple; }
 404 span.red-background { background: red; }
 405 span.silver-background { background: silver; }
 406 span.teal-background { background: teal; }
 407 span.white-background { background: white; }
 408 span.yellow-background { background: yellow; }
 409
 410 span.big { font-size: 2em; }
 411 span.small { font-size: 0.6em; }
 412
 413 span.underline { text-decoration: underline; }
 414 span.overline { text-decoration: overline; }
 415 span.line-through { text-decoration: line-through; }
 416
 417 div.unbreakable { page-break-inside: avoid; }
 418
 419
 420 /*
 421  * xhtml11 specific
 422  *
 423  * */
 424
 425 div.tableblock {
 426   margin-top: 1.0em;
 427   margin-bottom: 1.5em;
 428 }
 429 div.tableblock > table {
 430   border: 3px solid #527bbd;
 431 }
 432 thead, p.table.header {
 433   font-weight: bold;
 434   color: #527bbd;
 435 }
 436 p.table {
 437   margin-top: 0;
 438 }
 439 /* Because the table frame attribute is overridden by CSS in most browsers. */
 440 div.tableblock > table[frame="void"] {
 441   border-style: none;
 442 }
 443 div.tableblock > table[frame="hsides"] {
 444   border-left-style: none;
 445   border-right-style: none;
 446 }
 447 div.tableblock > table[frame="vsides"] {
 448   border-top-style: none;
 449   border-bottom-style: none;
 450 }
 451
 452
 453 /*
 454  * html5 specific
 455  *
 456  * */
 457
 458 table.tableblock {
 459   margin-top: 1.0em;
 460   margin-bottom: 1.5em;
 461 }
 462 thead, p.tableblock.header {
 463   font-weight: bold;
 464   color: #527bbd;
 465 }
 466 p.tableblock {
 467   margin-top: 0;
 468 }
 469 table.tableblock {
 470   border-width: 3px;
 471   border-spacing: 0px;
 472   border-style: solid;
 473   border-color: #527bbd;
 474   border-collapse: collapse;
 475 }
 476 th.tableblock, td.tableblock {
 477   border-width: 1px;
 478   padding: 4px;
 479   border-style: solid;
 480   border-color: #527bbd;
 481 }
 482
 483 table.tableblock.frame-topbot {
 484   border-left-style: hidden;
 485   border-right-style: hidden;
 486 }
 487 table.tableblock.frame-sides {
 488   border-top-style: hidden;
 489   border-bottom-style: hidden;
 490 }
 491 table.tableblock.frame-none {
 492   border-style: hidden;
 493 }
 494
 495 th.tableblock.halign-left, td.tableblock.halign-left {
 496   text-align: left;
 497 }
 498 th.tableblock.halign-center, td.tableblock.halign-center {
 499   text-align: center;
 500 }
 501 th.tableblock.halign-right, td.tableblock.halign-right {
 502   text-align: right;
 503 }
 504
 505 th.tableblock.valign-top, td.tableblock.valign-top {
 506   vertical-align: top;
 507 }
 508 th.tableblock.valign-middle, td.tableblock.valign-middle {
 509   vertical-align: middle;
 510 }
 511 th.tableblock.valign-bottom, td.tableblock.valign-bottom {
 512   vertical-align: bottom;
 513 }
 514
 515
 516 /*
 517  * manpage specific
 518  *
 519  * */
 520
 521 body.manpage h1 {
 522   padding-top: 0.5em;
 523   padding-bottom: 0.5em;
 524   border-top: 2px solid silver;
 525   border-bottom: 2px solid silver;
 526 }
 527 body.manpage h2 {
 528   border-style: none;
 529 }
 530 body.manpage div.sectionbody {
 531   margin-left: 3em;
 532 }
 533
 534 @media print {
 535   body.manpage div#toc { display: none; }
 536 }
 537
 538
 539 </style>
 540 <script type="text/javascript">
 541 /*<![CDATA[*/
 542 var asciidoc = {  // Namespace.
 543
 544 /////////////////////////////////////////////////////////////////////
 545 // Table Of Contents generator
 546 /////////////////////////////////////////////////////////////////////
 547
 548 /* Author: Mihai Bazon, September 2002
 549  * http://students.infoiasi.ro/~mishoo
 550  *
 551  * Table Of Content generator
 552  * Version: 0.4
 553  *
 554  * Feel free to use this script under the terms of the GNU General Public
 555  * License, as long as you do not remove or alter this notice.
 556  */
 557
 558  /* modified by Troy D. Hanson, September 2006. License: GPL */
 559  /* modified by Stuart Rackham, 2006, 2009. License: GPL */
 560
 561 // toclevels = 1..4.
 562 toc: function (toclevels) {
 563
 564   function getText(el) {
 565     var text = "";
 566     for (var i = el.firstChild; i != null; i = i.nextSibling) {
 567       if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
 568         text += i.data;
 569       else if (i.firstChild != null)
 570         text += getText(i);
 571     }
 572     return text;
 573   }
 574
 575   function TocEntry(el, text, toclevel) {
 576     this.element = el;
 577     this.text = text;
 578     this.toclevel = toclevel;
 579   }
 580
 581   function tocEntries(el, toclevels) {
 582     var result = new Array;
 583     var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
 584     // Function that scans the DOM tree for header elements (the DOM2
 585     // nodeIterator API would be a better technique but not supported by all
 586     // browsers).
 587     var iterate = function (el) {
 588       for (var i = el.firstChild; i != null; i = i.nextSibling) {
 589         if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
 590           var mo = re.exec(i.tagName);
 591           if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
 592             result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
 593           }
 594           iterate(i);
 595         }
 596       }
 597     }
 598     iterate(el);
 599     return result;
 600   }
 601
 602   var toc = document.getElementById("toc");
 603   if (!toc) {
 604     return;
 605   }
 606
 607   // Delete existing TOC entries in case we're reloading the TOC.
 608   var tocEntriesToRemove = [];
 609   var i;
 610   for (i = 0; i < toc.childNodes.length; i++) {
 611     var entry = toc.childNodes[i];
 612     if (entry.nodeName.toLowerCase() == 'div'
 613      && entry.getAttribute("class")
 614      && entry.getAttribute("class").match(/^toclevel/))
 615       tocEntriesToRemove.push(entry);
 616   }
 617   for (i = 0; i < tocEntriesToRemove.length; i++) {
 618     toc.removeChild(tocEntriesToRemove[i]);
 619   }
 620
 621   // Rebuild TOC entries.
 622   var entries = tocEntries(document.getElementById("content"), toclevels);
 623   for (var i = 0; i < entries.length; ++i) {
 624     var entry = entries[i];
 625     if (entry.element.id == "")
 626       entry.element.id = "_toc_" + i;
 627     var a = document.createElement("a");
 628     a.href = "#" + entry.element.id;
 629     a.appendChild(document.createTextNode(entry.text));
 630     var div = document.createElement("div");
 631     div.appendChild(a);
 632     div.className = "toclevel" + entry.toclevel;
 633     toc.appendChild(div);
 634   }
 635   if (entries.length == 0)
 636     toc.parentNode.removeChild(toc);
 637 },
 638
 639
 640 /////////////////////////////////////////////////////////////////////
 641 // Footnotes generator
 642 /////////////////////////////////////////////////////////////////////
 643
 644 /* Based on footnote generation code from:
 645  * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 646  */
 647
 648 footnotes: function () {
 649   // Delete existing footnote entries in case we're reloading the footnodes.
 650   var i;
 651   var noteholder = document.getElementById("footnotes");
 652   if (!noteholder) {
 653     return;
 654   }
 655   var entriesToRemove = [];
 656   for (i = 0; i < noteholder.childNodes.length; i++) {
 657     var entry = noteholder.childNodes[i];
 658     if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
 659       entriesToRemove.push(entry);
 660   }
 661   for (i = 0; i < entriesToRemove.length; i++) {
 662     noteholder.removeChild(entriesToRemove[i]);
 663   }
 664
 665   // Rebuild footnote entries.
 666   var cont = document.getElementById("content");
 667   var spans = cont.getElementsByTagName("span");
 668   var refs = {};
 669   var n = 0;
 670   for (i=0; i<spans.length; i++) {
 671     if (spans[i].className == "footnote") {
 672       n++;
 673       var note = spans[i].getAttribute("data-note");
 674       if (!note) {
 675         // Use [\s\S] in place of . so multi-line matches work.
 676         // Because JavaScript has no s (dotall) regex flag.
 677         note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
 678         spans[i].innerHTML =
 679           "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
 680           "' title='View footnote' class='footnote'>" + n + "</a>]";
 681         spans[i].setAttribute("data-note", note);
 682       }
 683       noteholder.innerHTML +=
 684         "<div class='footnote' id='_footnote_" + n + "'>" +
 685         "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
 686         n + "</a>. " + note + "</div>";
 687       var id =spans[i].getAttribute("id");
 688       if (id != null) refs["#"+id] = n;
 689     }
 690   }
 691   if (n == 0)
 692     noteholder.parentNode.removeChild(noteholder);
 693   else {
 694     // Process footnoterefs.
 695     for (i=0; i<spans.length; i++) {
 696       if (spans[i].className == "footnoteref") {
 697         var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
 698         href = href.match(/#.*/)[0];  // Because IE return full URL.
 699         n = refs[href];
 700         spans[i].innerHTML =
 701           "[<a href='#_footnote_" + n +
 702           "' title='View footnote' class='footnote'>" + n + "</a>]";
 703       }
 704     }
 705   }
 706 },
 707
 708 install: function(toclevels) {
 709   var timerId;
 710
 711   function reinstall() {
 712     asciidoc.footnotes();
 713     if (toclevels) {
 714       asciidoc.toc(toclevels);
 715     }
 716   }
 717
 718   function reinstallAndRemoveTimer() {
 719     clearInterval(timerId);
 720     reinstall();
 721   }
 722
 723   timerId = setInterval(reinstall, 500);
 724   if (document.addEventListener)
 725     document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
 726   else
 727     window.onload = reinstallAndRemoveTimer;
 728 }
 729
 730 }
 731 asciidoc.install();
 732 /*]]>*/
 733 </script>
 734 </head>
 735 <body class="manpage">
 736 <div id="header">
 737 <h1>
 738 gitcredentials(7) Manual Page
 739 </h1>
 740 <h2>NAME</h2>
 741 <div class="sectionbody">
 742 <p>gitcredentials -
 743    Providing usernames and passwords to Git
 744 </p>
 745 </div>
 746 </div>
 747 <div id="content">
 748 <div class="sect1">
 749 <h2 id="_synopsis">SYNOPSIS</h2>
 750 <div class="sectionbody">
 751 <div class="listingblock">
 752 <div class="content">
 753 <pre><code>git config credential.https://example.com.username myusername
 754 git config credential.helper "$helper $options"</code></pre>
 755 </div></div>
 756 </div>
 757 </div>
 758 <div class="sect1">
 759 <h2 id="_description">DESCRIPTION</h2>
 760 <div class="sectionbody">
 761 <div class="paragraph"><p>Git will sometimes need credentials from the user in order to perform
 762 operations; for example, it may need to ask for a username and password
 763 in order to access a remote repository over HTTP. Some remotes accept
 764 a personal access token or OAuth access token as a password. This
 765 manual describes the mechanisms Git uses to request these credentials,
 766 as well as some features to avoid inputting these credentials repeatedly.</p></div>
 767 </div>
 768 </div>
 769 <div class="sect1">
 770 <h2 id="_requesting_credentials">REQUESTING CREDENTIALS</h2>
 771 <div class="sectionbody">
 772 <div class="paragraph"><p>Without any credential helpers defined, Git will try the following
 773 strategies to ask the user for usernames and passwords:</p></div>
 774 <div class="olist arabic"><ol class="arabic">
 775 <li>
 776 <p>
 777 If the <code>GIT_ASKPASS</code> environment variable is set, the program
 778    specified by the variable is invoked. A suitable prompt is provided
 779    to the program on the command line, and the user&#8217;s input is read
 780    from its standard output.
 781 </p>
 782 </li>
 783 <li>
 784 <p>
 785 Otherwise, if the <code>core.askPass</code> configuration variable is set, its
 786    value is used as above.
 787 </p>
 788 </li>
 789 <li>
 790 <p>
 791 Otherwise, if the <code>SSH_ASKPASS</code> environment variable is set, its
 792    value is used as above.
 793 </p>
 794 </li>
 795 <li>
 796 <p>
 797 Otherwise, the user is prompted on the terminal.
 798 </p>
 799 </li>
 800 </ol></div>
 801 </div>
 802 </div>
 803 <div class="sect1">
 804 <h2 id="_avoiding_repetition">AVOIDING REPETITION</h2>
 805 <div class="sectionbody">
 806 <div class="paragraph"><p>It can be cumbersome to input the same credentials over and over.  Git
 807 provides two methods to reduce this annoyance:</p></div>
 808 <div class="olist arabic"><ol class="arabic">
 809 <li>
 810 <p>
 811 Static configuration of usernames for a given authentication context.
 812 </p>
 813 </li>
 814 <li>
 815 <p>
 816 Credential helpers to cache or store passwords, or to interact with
 817    a system password wallet or keychain.
 818 </p>
 819 </li>
 820 </ol></div>
 821 <div class="paragraph"><p>The first is simple and appropriate if you do not have secure storage available
 822 for a password. It is generally configured by adding this to your config:</p></div>
 823 <div class="listingblock">
 824 <div class="content">
 825 <pre><code>[credential "https://example.com"]
 826         username = me</code></pre>
 827 </div></div>
 828 <div class="paragraph"><p>Credential helpers, on the other hand, are external programs from which Git can
 829 request both usernames and passwords; they typically interface with secure
 830 storage provided by the OS or other programs. Alternatively, a
 831 credential-generating helper might generate credentials for certain servers via
 832 some API.</p></div>
 833 <div class="paragraph"><p>To use a helper, you must first select one to use. Git currently
 834 includes the following helpers:</p></div>
 835 <div class="dlist"><dl>
 836 <dt class="hdlist1">
 837 cache
 838 </dt>
 839 <dd>
 840 <p>
 841         Cache credentials in memory for a short period of time. See
 842         <a href="git-credential-cache.html">git-credential-cache(1)</a> for details.
 843 </p>
 844 </dd>
 845 <dt class="hdlist1">
 846 store
 847 </dt>
 848 <dd>
 849 <p>
 850         Store credentials indefinitely on disk. See
 851         <a href="git-credential-store.html">git-credential-store(1)</a> for details.
 852 </p>
 853 </dd>
 854 </dl></div>
 855 <div class="paragraph"><p>You may also have third-party helpers installed; search for
 856 <code>credential-*</code> in the output of <code>git help -a</code>, and consult the
 857 documentation of individual helpers.  Once you have selected a helper,
 858 you can tell Git to use it by putting its name into the
 859 credential.helper variable.</p></div>
 860 <div class="olist arabic"><ol class="arabic">
 861 <li>
 862 <p>
 863 Find a helper.
 864 </p>
 865 <div class="listingblock">
 866 <div class="content">
 867 <pre><code>$ git help -a | grep credential-
 868 credential-foo</code></pre>
 869 </div></div>
 870 </li>
 871 <li>
 872 <p>
 873 Read its description.
 874 </p>
 875 <div class="listingblock">
 876 <div class="content">
 877 <pre><code>$ git help credential-foo</code></pre>
 878 </div></div>
 879 </li>
 880 <li>
 881 <p>
 882 Tell Git to use it.
 883 </p>
 884 <div class="listingblock">
 885 <div class="content">
 886 <pre><code>$ git config --global credential.helper foo</code></pre>
 887 </div></div>
 888 </li>
 889 </ol></div>
 890 <div class="sect2">
 891 <h3 id="_available_helpers">Available helpers</h3>
 892 <div class="paragraph"><p>The community maintains a comprehensive list of Git credential helpers at
 893 <a href="https://git-scm.com/doc/credential-helpers">https://git-scm.com/doc/credential-helpers</a>.</p></div>
 894 </div>
 895 <div class="sect2">
 896 <h3 id="_oauth">OAuth</h3>
 897 <div class="paragraph"><p>An alternative to inputting passwords or personal access tokens is to use an
 898 OAuth credential helper. Initial authentication opens a browser window to the
 899 host. Subsequent authentication happens in the background. Many popular Git
 900 hosts support OAuth.</p></div>
 901 </div>
 902 </div>
 903 </div>
 904 <div class="sect1">
 905 <h2 id="_credential_contexts">CREDENTIAL CONTEXTS</h2>
 906 <div class="sectionbody">
 907 <div class="paragraph"><p>Git considers each credential to have a context defined by a URL. This context
 908 is used to look up context-specific configuration, and is passed to any
 909 helpers, which may use it as an index into secure storage.</p></div>
 910 <div class="paragraph"><p>For instance, imagine we are accessing <code>https://example.com/foo.git</code>. When Git
 911 looks into a config file to see if a section matches this context, it will
 912 consider the two a match if the context is a more-specific subset of the
 913 pattern in the config file. For example, if you have this in your config file:</p></div>
 914 <div class="listingblock">
 915 <div class="content">
 916 <pre><code>[credential "https://example.com"]
 917         username = foo</code></pre>
 918 </div></div>
 919 <div class="paragraph"><p>then we will match: both protocols are the same, both hosts are the same, and
 920 the "pattern" URL does not care about the path component at all. However, this
 921 context would not match:</p></div>
 922 <div class="listingblock">
 923 <div class="content">
 924 <pre><code>[credential "https://kernel.org"]
 925         username = foo</code></pre>
 926 </div></div>
 927 <div class="paragraph"><p>because the hostnames differ. Nor would it match <code>foo.example.com</code>; Git
 928 compares hostnames exactly, without considering whether two hosts are part of
 929 the same domain. Likewise, a config entry for <code>http://example.com</code> would not
 930 match: Git compares the protocols exactly.  However, you may use wildcards in
 931 the domain name and other pattern matching techniques as with the <code>http.&lt;URL&gt;.*</code>
 932 options.</p></div>
 933 <div class="paragraph"><p>If the "pattern" URL does include a path component, then this too must match
 934 exactly: the context <code>https://example.com/bar/baz.git</code> will match a config
 935 entry for <code>https://example.com/bar/baz.git</code> (in addition to matching the config
 936 entry for <code>https://example.com</code>) but will not match a config entry for
 937 <code>https://example.com/bar</code>.</p></div>
 938 </div>
 939 </div>
 940 <div class="sect1">
 941 <h2 id="_configuration_options">CONFIGURATION OPTIONS</h2>
 942 <div class="sectionbody">
 943 <div class="paragraph"><p>Options for a credential context can be configured either in
 944 <code>credential.*</code> (which applies to all credentials), or
 945 <code>credential.&lt;URL&gt;.*</code>, where &lt;URL&gt; matches the context as described
 946 above.</p></div>
 947 <div class="paragraph"><p>The following options are available in either location:</p></div>
 948 <div class="dlist"><dl>
 949 <dt class="hdlist1">
 950 helper
 951 </dt>
 952 <dd>
 953 <p>
 954         The name of an external credential helper, and any associated options.
 955         If the helper name is not an absolute path, then the string <code>git
 956         credential-</code> is prepended. The resulting string is executed by the
 957         shell (so, for example, setting this to <code>foo --option=bar</code> will execute
 958         <code>git credential-foo --option=bar</code> via the shell. See the manual of
 959         specific helpers for examples of their use.
 960 </p>
 961 <div class="paragraph"><p>If there are multiple instances of the <code>credential.helper</code> configuration
 962 variable, each helper will be tried in turn, and may provide a username,
 963 password, or nothing. Once Git has acquired both a username and a
 964 non-expired password, no more helpers will be tried.</p></div>
 965 <div class="paragraph"><p>If <code>credential.helper</code> is configured to the empty string, this resets
 966 the helper list to empty (so you may override a helper set by a
 967 lower-priority config file by configuring the empty-string helper,
 968 followed by whatever set of helpers you would like).</p></div>
 969 </dd>
 970 <dt class="hdlist1">
 971 username
 972 </dt>
 973 <dd>
 974 <p>
 975         A default username, if one is not provided in the URL.
 976 </p>
 977 </dd>
 978 <dt class="hdlist1">
 979 useHttpPath
 980 </dt>
 981 <dd>
 982 <p>
 983         By default, Git does not consider the "path" component of an http URL
 984         to be worth matching via external helpers. This means that a credential
 985         stored for <code>https://example.com/foo.git</code> will also be used for
 986         <code>https://example.com/bar.git</code>. If you do want to distinguish these
 987         cases, set this option to <code>true</code>.
 988 </p>
 989 </dd>
 990 </dl></div>
 991 </div>
 992 </div>
 993 <div class="sect1">
 994 <h2 id="_custom_helpers">CUSTOM HELPERS</h2>
 995 <div class="sectionbody">
 996 <div class="paragraph"><p>You can write your own custom helpers to interface with any system in
 997 which you keep credentials.</p></div>
 998 <div class="paragraph"><p>Credential helpers are programs executed by Git to fetch or save
 999 credentials from and to long-term storage (where "long-term" is simply
1000 longer than a single Git process; e.g., credentials may be stored
1001 in-memory for a few minutes, or indefinitely on disk).</p></div>
1002 <div class="paragraph"><p>Each helper is specified by a single string in the configuration
1003 variable <code>credential.helper</code> (and others, see <a href="git-config.html">git-config(1)</a>).
1004 The string is transformed by Git into a command to be executed using
1005 these rules:</p></div>
1006 <div class="olist arabic"><ol class="arabic">
1007 <li>
1008 <p>
1009 If the helper string begins with "!", it is considered a shell
1010      snippet, and everything after the "!" becomes the command.
1011 </p>
1012 </li>
1013 <li>
1014 <p>
1015 Otherwise, if the helper string begins with an absolute path, the
1016      verbatim helper string becomes the command.
1017 </p>
1018 </li>
1019 <li>
1020 <p>
1021 Otherwise, the string "git credential-" is prepended to the helper
1022      string, and the result becomes the command.
1023 </p>
1024 </li>
1025 </ol></div>
1026 <div class="paragraph"><p>The resulting command then has an "operation" argument appended to it
1027 (see below for details), and the result is executed by the shell.</p></div>
1028 <div class="paragraph"><p>Here are some example specifications:</p></div>
1029 <div class="listingblock">
1030 <div class="content">
1031 <pre><code># run "git credential-foo"
1032 [credential]
1033         helper = foo
1034
1035 # same as above, but pass an argument to the helper
1036 [credential]
1037         helper = "foo --bar=baz"
1038
1039 # the arguments are parsed by the shell, so use shell
1040 # quoting if necessary
1041 [credential]
1042         helper = "foo --bar='whitespace arg'"
1043
1044 # you can also use an absolute path, which will not use the git wrapper
1045 [credential]
1046         helper = "/path/to/my/helper --with-arguments"
1047
1048 # or you can specify your own shell snippet
1049 [credential "https://example.com"]
1050         username = your_user
1051         helper = "!f() { test \"$1\" = get &amp;&amp; echo \"password=$(cat $HOME/.secret)\"; }; f"</code></pre>
1052 </div></div>
1053 <div class="paragraph"><p>Generally speaking, rule (3) above is the simplest for users to specify.
1054 Authors of credential helpers should make an effort to assist their
1055 users by naming their program "git-credential-$NAME", and putting it in
1056 the <code>$PATH</code> or <code>$GIT_EXEC_PATH</code> during installation, which will allow a
1057 user to enable it with <code>git config credential.helper $NAME</code>.</p></div>
1058 <div class="paragraph"><p>When a helper is executed, it will have one "operation" argument
1059 appended to its command line, which is one of:</p></div>
1060 <div class="dlist"><dl>
1061 <dt class="hdlist1">
1062 <code>get</code>
1063 </dt>
1064 <dd>
1065 <p>
1066         Return a matching credential, if any exists.
1067 </p>
1068 </dd>
1069 <dt class="hdlist1">
1070 <code>store</code>
1071 </dt>
1072 <dd>
1073 <p>
1074         Store the credential, if applicable to the helper.
1075 </p>
1076 </dd>
1077 <dt class="hdlist1">
1078 <code>erase</code>
1079 </dt>
1080 <dd>
1081 <p>
1082         Remove matching credentials, if any, from the helper&#8217;s storage.
1083 </p>
1084 </dd>
1085 </dl></div>
1086 <div class="paragraph"><p>The details of the credential will be provided on the helper&#8217;s stdin
1087 stream. The exact format is the same as the input/output format of the
1088 <code>git credential</code> plumbing command (see the section <code>INPUT/OUTPUT
1089 FORMAT</code> in <a href="git-credential.html">git-credential(1)</a> for a detailed specification).</p></div>
1090 <div class="paragraph"><p>For a <code>get</code> operation, the helper should produce a list of attributes on
1091 stdout in the same format (see <a href="git-credential.html">git-credential(1)</a> for common
1092 attributes). A helper is free to produce a subset, or even no values at
1093 all if it has nothing useful to provide. Any provided attributes will
1094 overwrite those already known about by Git&#8217;s credential subsystem.
1095 Unrecognised attributes are silently discarded.</p></div>
1096 <div class="paragraph"><p>While it is possible to override all attributes, well behaving helpers
1097 should refrain from doing so for any attribute other than username and
1098 password.</p></div>
1099 <div class="paragraph"><p>If a helper outputs a <code>quit</code> attribute with a value of <code>true</code> or <code>1</code>,
1100 no further helpers will be consulted, nor will the user be prompted
1101 (if no credential has been provided, the operation will then fail).</p></div>
1102 <div class="paragraph"><p>Similarly, no more helpers will be consulted once both username and
1103 password had been provided.</p></div>
1104 <div class="paragraph"><p>For a <code>store</code> or <code>erase</code> operation, the helper&#8217;s output is ignored.</p></div>
1105 <div class="paragraph"><p>If a helper fails to perform the requested operation or needs to notify
1106 the user of a potential issue, it may write to stderr.</p></div>
1107 <div class="paragraph"><p>If it does not support the requested operation (e.g., a read-only store
1108 or generator), it should silently ignore the request.</p></div>
1109 <div class="paragraph"><p>If a helper receives any other operation, it should silently ignore the
1110 request. This leaves room for future operations to be added (older
1111 helpers will just ignore the new requests).</p></div>
1112 </div>
1113 </div>
1114 <div class="sect1">
1115 <h2 id="_git">GIT</h2>
1116 <div class="sectionbody">
1117 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
1118 </div>
1119 </div>
1120 </div>
1121 <div id="footnotes"><hr /></div>
1122 <div id="footer">
1123 <div id="footer-text">
1124 Last updated
1125  2023-07-18 08:52:58 PDT
1126 </div>
1127 </div>
1128 </body>
1129 </html>