gitfaq.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>gitfaq(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 gitfaq(7) Manual Page
 739 </h1>
 740 <h2>NAME</h2>
 741 <div class="sectionbody">
 742 <p>gitfaq -
 743    Frequently asked questions about using 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="paragraph"><p>gitfaq</p></div>
 752 </div>
 753 </div>
 754 <div class="sect1">
 755 <h2 id="_description">DESCRIPTION</h2>
 756 <div class="sectionbody">
 757 <div class="paragraph"><p>The examples in this FAQ assume a standard POSIX shell, like <code>bash</code> or <code>dash</code>,
 758 and a user, A U Thor, who has the account <code>author</code> on the hosting provider
 759 <code>git.example.org</code>.</p></div>
 760 </div>
 761 </div>
 762 <div class="sect1">
 763 <h2 id="_configuration">Configuration</h2>
 764 <div class="sectionbody">
 765 <div class="dlist" id="user-name"><dl>
 766 <dt class="hdlist1">
 767 What should I put in <code>user.name</code>?
 768 </dt>
 769 <dd>
 770 <p>
 771         You should put your personal name, generally a form using a given name
 772         and family name.  For example, the current maintainer of Git uses "Junio
 773         C Hamano".  This will be the name portion that is stored in every commit
 774         you make.
 775 </p>
 776 <div class="paragraph"><p>This configuration doesn&#8217;t have any effect on authenticating to remote services;
 777 for that, see <code>credential.username</code> in <a href="git-config.html">git-config(1)</a>.</p></div>
 778 </dd>
 779 <dt class="hdlist1">
 780 What does <code>http.postBuffer</code> really do?
 781 </dt>
 782 <dd>
 783 <p>
 784         This option changes the size of the buffer that Git uses when pushing
 785         data to a remote over HTTP or HTTPS.  If the data is larger than this
 786         size, libcurl, which handles the HTTP support for Git, will use chunked
 787         transfer encoding since it isn&#8217;t known ahead of time what the size of
 788         the pushed data will be.
 789 </p>
 790 <div class="paragraph" id="http-postbuffer"><p>Leaving this value at the default size is fine unless you know that either the
 791 remote server or a proxy in the middle doesn&#8217;t support HTTP/1.1 (which
 792 introduced the chunked transfer encoding) or is known to be broken with chunked
 793 data.  This is often (erroneously) suggested as a solution for generic push
 794 problems, but since almost every server and proxy supports at least HTTP/1.1,
 795 raising this value usually doesn&#8217;t solve most push problems.  A server or proxy
 796 that didn&#8217;t correctly support HTTP/1.1 and chunked transfer encoding wouldn&#8217;t be
 797 that useful on the Internet today, since it would break lots of traffic.</p></div>
 798 <div class="paragraph"><p>Note that increasing this value will increase the memory used on every relevant
 799 push that Git does over HTTP or HTTPS, since the entire buffer is allocated
 800 regardless of whether or not it is all used.  Thus, it&#8217;s best to leave it at the
 801 default unless you are sure you need a different value.</p></div>
 802 </dd>
 803 <dt class="hdlist1">
 804 How do I configure a different editor?
 805 </dt>
 806 <dd>
 807 <p>
 808         If you haven&#8217;t specified an editor specifically for Git, it will by default
 809         use the editor you&#8217;ve configured using the <code>VISUAL</code> or <code>EDITOR</code> environment
 810         variables, or if neither is specified, the system default (which is usually
 811         <code>vi</code>).  Since some people find <code>vi</code> difficult to use or prefer a different
 812         editor, it may be desirable to change the editor used.
 813 </p>
 814 <div class="paragraph" id="configure-editor"><p>If you want to configure a general editor for most programs which need one, you
 815 can edit your shell configuration (e.g., <code>~/.bashrc</code> or <code>~/.zshenv</code>) to contain
 816 a line setting the <code>EDITOR</code> or <code>VISUAL</code> environment variable to an appropriate
 817 value.  For example, if you prefer the editor <code>nano</code>, then you could write the
 818 following:</p></div>
 819 <div class="listingblock">
 820 <div class="content">
 821 <pre><code>export VISUAL=nano</code></pre>
 822 </div></div>
 823 <div class="paragraph"><p>If you want to configure an editor specifically for Git, you can either set the
 824 <code>core.editor</code> configuration value or the <code>GIT_EDITOR</code> environment variable.  You
 825 can see <a href="git-var.html">git-var(1)</a> for details on the order in which these options are
 826 consulted.</p></div>
 827 <div class="paragraph"><p>Note that in all cases, the editor value will be passed to the shell, so any
 828 arguments containing spaces should be appropriately quoted.  Additionally, if
 829 your editor normally detaches from the terminal when invoked, you should specify
 830 it with an argument that makes it not do that, or else Git will not see any
 831 changes.  An example of a configuration addressing both of these issues on
 832 Windows would be the configuration <code>"C:\Program Files\Vim\gvim.exe" --nofork</code>,
 833 which quotes the filename with spaces and specifies the <code>--nofork</code> option to
 834 avoid backgrounding the process.</p></div>
 835 </dd>
 836 </dl></div>
 837 </div>
 838 </div>
 839 <div class="sect1">
 840 <h2 id="_credentials">Credentials</h2>
 841 <div class="sectionbody">
 842 <div class="dlist" id="http-credentials"><dl>
 843 <dt class="hdlist1">
 844 How do I specify my credentials when pushing over HTTP?
 845 </dt>
 846 <dd>
 847 <p>
 848         The easiest way to do this is to use a credential helper via the
 849         <code>credential.helper</code> configuration.  Most systems provide a standard
 850         choice to integrate with the system credential manager.  For example,
 851         Git for Windows provides the <code>wincred</code> credential manager, macOS has the
 852         <code>osxkeychain</code> credential manager, and Unix systems with a standard
 853         desktop environment can use the <code>libsecret</code> credential manager.  All of
 854         these store credentials in an encrypted store to keep your passwords or
 855         tokens secure.
 856 </p>
 857 <div class="paragraph"><p>In addition, you can use the <code>store</code> credential manager which stores in a file
 858 in your home directory, or the <code>cache</code> credential manager, which does not
 859 permanently store your credentials, but does prevent you from being prompted for
 860 them for a certain period of time.</p></div>
 861 <div class="paragraph"><p>You can also just enter your password when prompted.  While it is possible to
 862 place the password (which must be percent-encoded) in the URL, this is not
 863 particularly secure and can lead to accidental exposure of credentials, so it is
 864 not recommended.</p></div>
 865 </dd>
 866 <dt class="hdlist1">
 867 How do I read a password or token from an environment variable?
 868 </dt>
 869 <dd>
 870 <p>
 871         The <code>credential.helper</code> configuration option can also take an arbitrary
 872         shell command that produces the credential protocol on standard output.
 873         This is useful when passing credentials into a container, for example.
 874 </p>
 875 <div class="paragraph" id="http-credentials-environment"><p>Such a shell command can be specified by starting the option value with an
 876 exclamation point.  If your password or token were stored in the <code>GIT_TOKEN</code>,
 877 you could run the following command to set your credential helper:</p></div>
 878 <div class="listingblock">
 879 <div class="content">
 880 <pre><code>$ git config credential.helper \
 881         '!f() { echo username=author; echo "password=$GIT_TOKEN"; };f'</code></pre>
 882 </div></div>
 883 </dd>
 884 <dt class="hdlist1">
 885 How do I change the password or token I&#8217;ve saved in my credential manager?
 886 </dt>
 887 <dd>
 888 <p>
 889         Usually, if the password or token is invalid, Git will erase it and
 890         prompt for a new one.  However, there are times when this doesn&#8217;t always
 891         happen.  To change the password or token, you can erase the existing
 892         credentials and then Git will prompt for new ones.  To erase
 893         credentials, use a syntax like the following (substituting your username
 894         and the hostname):
 895 </p>
 896 <div class="listingblock" id="http-reset-credentials">
 897 <div class="content">
 898 <pre><code>$ echo url=https://author@git.example.org | git credential reject</code></pre>
 899 </div></div>
 900 </dd>
 901 <dt class="hdlist1">
 902 How do I use multiple accounts with the same hosting provider using HTTP?
 903 </dt>
 904 <dd>
 905 <p>
 906         Usually the easiest way to distinguish between these accounts is to use
 907         the username in the URL.  For example, if you have the accounts <code>author</code>
 908         and <code>committer</code> on <code>git.example.org</code>, you can use the URLs
 909         <a href="https://author@git.example.org/org1/project1.git">https://author@git.example.org/org1/project1.git</a> and
 910         <a href="https://committer@git.example.org/org2/project2.git">https://committer@git.example.org/org2/project2.git</a>.  This way, when you
 911         use a credential helper, it will automatically try to look up the
 912         correct credentials for your account.  If you already have a remote set
 913         up, you can change the URL with something like <code>git remote set-url
 914         origin https://author@git.example.org/org1/project1.git</code> (see
 915         <a href="git-remote.html">git-remote(1)</a> for details).
 916 </p>
 917 </dd>
 918 <dt class="hdlist1">
 919 How do I use multiple accounts with the same hosting provider using SSH?
 920 </dt>
 921 <dd>
 922 <p>
 923         With most hosting providers that support SSH, a single key pair uniquely
 924         identifies a user.  Therefore, to use multiple accounts, it&#8217;s necessary
 925         to create a key pair for each account.  If you&#8217;re using a reasonably
 926         modern OpenSSH version, you can create a new key pair with something
 927         like <code>ssh-keygen -t ed25519 -f ~/.ssh/id_committer</code>.  You can then
 928         register the public key (in this case, <code>~/.ssh/id_committer.pub</code>; note
 929         the <code>.pub</code>) with the hosting provider.
 930 </p>
 931 <div class="paragraph" id="multiple-accounts-ssh"><p>Most hosting providers use a single SSH account for pushing; that is, all users
 932 push to the <code>git</code> account (e.g., <code>git@git.example.org</code>).  If that&#8217;s the case for
 933 your provider, you can set up multiple aliases in SSH to make it clear which key
 934 pair to use.  For example, you could write something like the following in
 935 <code>~/.ssh/config</code>, substituting the proper private key file:</p></div>
 936 <div class="listingblock">
 937 <div class="content">
 938 <pre><code># This is the account for author on git.example.org.
 939 Host example_author
 940         HostName git.example.org
 941         User git
 942         # This is the key pair registered for author with git.example.org.
 943         IdentityFile ~/.ssh/id_author
 944         IdentitiesOnly yes
 945 # This is the account for committer on git.example.org.
 946 Host example_committer
 947         HostName git.example.org
 948         User git
 949         # This is the key pair registered for committer with git.example.org.
 950         IdentityFile ~/.ssh/id_committer
 951         IdentitiesOnly yes</code></pre>
 952 </div></div>
 953 <div class="paragraph"><p>Then, you can adjust your push URL to use <code>git@example_author</code> or
 954 <code>git@example_committer</code> instead of <code>git@example.org</code> (e.g., <code>git remote set-url
 955 git@example_author:org1/project1.git</code>).</p></div>
 956 </dd>
 957 </dl></div>
 958 </div>
 959 </div>
 960 <div class="sect1">
 961 <h2 id="_common_issues">Common Issues</h2>
 962 <div class="sectionbody">
 963 <div class="dlist" id="last-commit-amend"><dl>
 964 <dt class="hdlist1">
 965 I&#8217;ve made a mistake in the last commit.  How do I change it?
 966 </dt>
 967 <dd>
 968 <p>
 969         You can make the appropriate change to your working tree, run <code>git add
 970         &lt;file&gt;</code> or <code>git rm &lt;file&gt;</code>, as appropriate, to stage it, and then <code>git
 971         commit --amend</code>.  Your change will be included in the commit, and you&#8217;ll
 972         be prompted to edit the commit message again; if you wish to use the
 973         original message verbatim, you can use the <code>--no-edit</code> option to <code>git
 974         commit</code> in addition, or just save and quit when your editor opens.
 975 </p>
 976 </dd>
 977 <dt class="hdlist1">
 978 I&#8217;ve made a change with a bug and it&#8217;s been included in the main branch.  How should I undo it?
 979 </dt>
 980 <dd>
 981 <p>
 982         The usual way to deal with this is to use <code>git revert</code>.  This preserves
 983         the history that the original change was made and was a valuable
 984         contribution, but also introduces a new commit that undoes those changes
 985         because the original had a problem.  The commit message of the revert
 986         indicates the commit which was reverted and is usually edited to include
 987         an explanation as to why the revert was made.
 988 </p>
 989 </dd>
 990 <dt class="hdlist1">
 991 How do I ignore changes to a tracked file?
 992 </dt>
 993 <dd>
 994 <p>
 995         Git doesn&#8217;t provide a way to do this.  The reason is that if Git needs
 996         to overwrite this file, such as during a checkout, it doesn&#8217;t know
 997         whether the changes to the file are precious and should be kept, or
 998         whether they are irrelevant and can safely be destroyed.  Therefore, it
 999         has to take the safe route and always preserve them.
1000 </p>
1001 <div class="paragraph" id="ignore-tracked-files"><p>It&#8217;s tempting to try to use certain features of <code>git update-index</code>, namely the
1002 assume-unchanged and skip-worktree bits, but these don&#8217;t work properly for this
1003 purpose and shouldn&#8217;t be used this way.</p></div>
1004 <div class="paragraph"><p>If your goal is to modify a configuration file, it can often be helpful to have
1005 a file checked into the repository which is a template or set of defaults which
1006 can then be copied alongside and modified as appropriate.  This second, modified
1007 file is usually ignored to prevent accidentally committing it.</p></div>
1008 </dd>
1009 <dt class="hdlist1">
1010 I asked Git to ignore various files, yet they are still tracked
1011 </dt>
1012 <dd>
1013 <p>
1014         A <code>gitignore</code> file ensures that certain file(s) which are not
1015         tracked by Git remain untracked.  However, sometimes particular
1016         file(s) may have been tracked before adding them into the
1017         <code>.gitignore</code>, hence they still remain tracked.  To untrack and
1018         ignore files/patterns, use <code>git rm --cached &lt;file/pattern&gt;</code>
1019         and add a pattern to <code>.gitignore</code> that matches the &lt;file&gt;.
1020         See <a href="gitignore.html">gitignore(5)</a> for details.
1021 </p>
1022 </dd>
1023 <dt class="hdlist1">
1024 How do I know if I want to do a fetch or a pull?
1025 </dt>
1026 <dd>
1027 <p>
1028         A fetch stores a copy of the latest changes from the remote
1029         repository, without modifying the working tree or current branch.
1030         You can then at your leisure inspect, merge, rebase on top of, or
1031         ignore the upstream changes.  A pull consists of a fetch followed
1032         immediately by either a merge or rebase.  See <a href="git-pull.html">git-pull(1)</a>.
1033 </p>
1034 </dd>
1035 </dl></div>
1036 </div>
1037 </div>
1038 <div class="sect1">
1039 <h2 id="fetching-and-pulling">Merging and Rebasing</h2>
1040 <div class="sectionbody">
1041 <div class="dlist" id="long-running-squash-merge"><dl>
1042 <dt class="hdlist1">
1043 What kinds of problems can occur when merging long-lived branches with squash merges?
1044 </dt>
1045 <dd>
1046 <p>
1047         In general, there are a variety of problems that can occur when using squash
1048         merges to merge two branches multiple times.  These can include seeing extra
1049         commits in <code>git log</code> output, with a GUI, or when using the <code>...</code> notation to
1050         express a range, as well as the possibility of needing to re-resolve conflicts
1051         again and again.
1052 </p>
1053 <div class="paragraph"><p>When Git does a normal merge between two branches, it considers exactly three
1054 points: the two branches and a third commit, called the <em>merge base</em>, which is
1055 usually the common ancestor of the commits.  The result of the merge is the sum
1056 of the changes between the merge base and each head.  When you merge two
1057 branches with a regular merge commit, this results in a new commit which will
1058 end up as a merge base when they&#8217;re merged again, because there is now a new
1059 common ancestor.  Git doesn&#8217;t have to consider changes that occurred before the
1060 merge base, so you don&#8217;t have to re-resolve any conflicts you resolved before.</p></div>
1061 <div class="paragraph"><p>When you perform a squash merge, a merge commit isn&#8217;t created; instead, the
1062 changes from one side are applied as a regular commit to the other side.  This
1063 means that the merge base for these branches won&#8217;t have changed, and so when Git
1064 goes to perform its next merge, it considers all of the changes that it
1065 considered the last time plus the new changes.  That means any conflicts may
1066 need to be re-resolved.  Similarly, anything using the <code>...</code> notation in <code>git
1067 diff</code>, <code>git log</code>, or a GUI will result in showing all of the changes since the
1068 original merge base.</p></div>
1069 <div class="paragraph"><p>As a consequence, if you want to merge two long-lived branches repeatedly, it&#8217;s
1070 best to always use a regular merge commit.</p></div>
1071 </dd>
1072 <dt class="hdlist1">
1073 If I make a change on two branches but revert it on one, why does the merge of those branches include the change?
1074 </dt>
1075 <dd>
1076 <p>
1077         By default, when Git does a merge, it uses a strategy called the <code>ort</code>
1078         strategy, which does a fancy three-way merge.  In such a case, when Git
1079         performs the merge, it considers exactly three points: the two heads and a
1080         third point, called the <em>merge base</em>, which is usually the common ancestor of
1081         those commits.  Git does not consider the history or the individual commits
1082         that have happened on those branches at all.
1083 </p>
1084 <div class="paragraph" id="merge-two-revert-one"><p>As a result, if both sides have a change and one side has reverted that change,
1085 the result is to include the change.  This is because the code has changed on
1086 one side and there is no net change on the other, and in this scenario, Git
1087 adopts the change.</p></div>
1088 <div class="paragraph"><p>If this is a problem for you, you can do a rebase instead, rebasing the branch
1089 with the revert onto the other branch.  A rebase in this scenario will revert
1090 the change, because a rebase applies each individual commit, including the
1091 revert.  Note that rebases rewrite history, so you should avoid rebasing
1092 published branches unless you&#8217;re sure you&#8217;re comfortable with that.  See the
1093 NOTES section in <a href="git-rebase.html">git-rebase(1)</a> for more details.</p></div>
1094 </dd>
1095 </dl></div>
1096 </div>
1097 </div>
1098 <div class="sect1">
1099 <h2 id="_hooks">Hooks</h2>
1100 <div class="sectionbody">
1101 <div class="dlist" id="restrict-with-hooks"><dl>
1102 <dt class="hdlist1">
1103 How do I use hooks to prevent users from making certain changes?
1104 </dt>
1105 <dd>
1106 <p>
1107         The only safe place to make these changes is on the remote repository
1108         (i.e., the Git server), usually in the <code>pre-receive</code> hook or in a
1109         continuous integration (CI) system.  These are the locations in which
1110         policy can be enforced effectively.
1111 </p>
1112 <div class="paragraph"><p>It&#8217;s common to try to use <code>pre-commit</code> hooks (or, for commit messages,
1113 <code>commit-msg</code> hooks) to check these things, which is great if you&#8217;re working as a
1114 solo developer and want the tooling to help you.  However, using hooks on a
1115 developer machine is not effective as a policy control because a user can bypass
1116 these hooks with <code>--no-verify</code> without being noticed (among various other ways).
1117 Git assumes that the user is in control of their local repositories and doesn&#8217;t
1118 try to prevent this or tattle on the user.</p></div>
1119 <div class="paragraph"><p>In addition, some advanced users find <code>pre-commit</code> hooks to be an impediment to
1120 workflows that use temporary commits to stage work in progress or that create
1121 fixup commits, so it&#8217;s better to push these kinds of checks to the server
1122 anyway.</p></div>
1123 </dd>
1124 </dl></div>
1125 </div>
1126 </div>
1127 <div class="sect1">
1128 <h2 id="_cross_platform_issues">Cross-Platform Issues</h2>
1129 <div class="sectionbody">
1130 <div class="dlist" id="windows-text-binary"><dl>
1131 <dt class="hdlist1">
1132 I&#8217;m on Windows and my text files are detected as binary.
1133 </dt>
1134 <dd>
1135 <p>
1136         Git works best when you store text files as UTF-8.  Many programs on
1137         Windows support UTF-8, but some do not and only use the little-endian
1138         UTF-16 format, which Git detects as binary.  If you can&#8217;t use UTF-8 with
1139         your programs, you can specify a working tree encoding that indicates
1140         which encoding your files should be checked out with, while still
1141         storing these files as UTF-8 in the repository.  This allows tools like
1142         <a href="git-diff.html">git-diff(1)</a> to work as expected, while still allowing your tools
1143         to work.
1144 </p>
1145 <div class="paragraph"><p>To do so, you can specify a <a href="gitattributes.html">gitattributes(5)</a> pattern with the
1146 <code>working-tree-encoding</code> attribute.  For example, the following pattern sets all
1147 C files to use UTF-16LE-BOM, which is a common encoding on Windows:</p></div>
1148 <div class="listingblock">
1149 <div class="content">
1150 <pre><code>*.c     working-tree-encoding=UTF-16LE-BOM</code></pre>
1151 </div></div>
1152 <div class="paragraph"><p>You will need to run <code>git add --renormalize</code> to have this take effect.  Note
1153 that if you are making these changes on a project that is used across platforms,
1154 you&#8217;ll probably want to make it in a per-user configuration file or in the one
1155 in <code>$GIT_DIR/info/attributes</code>, since making it in a <code>.gitattributes</code> file in the
1156 repository will apply to all users of the repository.</p></div>
1157 <div class="paragraph"><p>See the following entry for information about normalizing line endings as well,
1158 and see <a href="gitattributes.html">gitattributes(5)</a> for more information about attribute files.</p></div>
1159 </dd>
1160 <dt class="hdlist1">
1161 I&#8217;m on Windows and git diff shows my files as having a <code>^M</code> at the end.
1162 </dt>
1163 <dd>
1164 <p>
1165         By default, Git expects files to be stored with Unix line endings.  As such,
1166         the carriage return (<code>^M</code>) that is part of a Windows line ending is shown
1167         because it is considered to be trailing whitespace.  Git defaults to showing
1168         trailing whitespace only on new lines, not existing ones.
1169 </p>
1170 <div class="paragraph" id="windows-diff-control-m"><p>You can store the files in the repository with Unix line endings and convert
1171 them automatically to your platform&#8217;s line endings.  To do that, set the
1172 configuration option <code>core.eol</code> to <code>native</code> and see the following entry for
1173 information about how to configure files as text or binary.</p></div>
1174 <div class="paragraph"><p>You can also control this behavior with the <code>core.whitespace</code> setting if you
1175 don&#8217;t wish to remove the carriage returns from your line endings.</p></div>
1176 </dd>
1177 <dt class="hdlist1">
1178 Why do I have a file that&#8217;s always modified?
1179 </dt>
1180 <dd>
1181 <p>
1182         Internally, Git always stores file names as sequences of bytes and doesn&#8217;t
1183         perform any encoding or case folding.  However, Windows and macOS by default
1184         both perform case folding on file names.  As a result, it&#8217;s possible to end up
1185         with multiple files or directories whose names differ only in case.  Git can
1186         handle this just fine, but the file system can store only one of these files,
1187         so when Git reads the other file to see its contents, it looks modified.
1188 </p>
1189 <div class="paragraph" id="always-modified-files-case"><p>It&#8217;s best to remove one of the files such that you only have one file.  You can
1190 do this with commands like the following (assuming two files <code>AFile.txt</code> and
1191 <code>afile.txt</code>) on an otherwise clean working tree:</p></div>
1192 <div class="listingblock">
1193 <div class="content">
1194 <pre><code>$ git rm --cached AFile.txt
1195 $ git commit -m 'Remove files conflicting in case'
1196 $ git checkout .</code></pre>
1197 </div></div>
1198 <div class="paragraph"><p>This avoids touching the disk, but removes the additional file.  Your project
1199 may prefer to adopt a naming convention, such as all-lowercase names, to avoid
1200 this problem from occurring again; such a convention can be checked using a
1201 <code>pre-receive</code> hook or as part of a continuous integration (CI) system.</p></div>
1202 <div class="paragraph"><p>It is also possible for perpetually modified files to occur on any platform if a
1203 smudge or clean filter is in use on your system but a file was previously
1204 committed without running the smudge or clean filter.  To fix this, run the
1205 following on an otherwise clean working tree:</p></div>
1206 <div class="listingblock">
1207 <div class="content">
1208 <pre><code>$ git add --renormalize .</code></pre>
1209 </div></div>
1210 </dd>
1211 <dt class="hdlist1">
1212 What&#8217;s the recommended way to store files in Git?
1213 </dt>
1214 <dd>
1215 <p>
1216         While Git can store and handle any file of any type, there are some
1217         settings that work better than others.  In general, we recommend that
1218         text files be stored in UTF-8 without a byte-order mark (BOM) with LF
1219         (Unix-style) endings.  We also recommend the use of UTF-8 (again,
1220         without BOM) in commit messages.  These are the settings that work best
1221         across platforms and with tools such as <code>git diff</code> and <code>git merge</code>.
1222 </p>
1223 <div class="paragraph" id="recommended-storage-settings"><p>Additionally, if you have a choice between storage formats that are text based
1224 or non-text based, we recommend storing files in the text format and, if
1225 necessary, transforming them into the other format.  For example, a text-based
1226 SQL dump with one record per line will work much better for diffing and merging
1227 than an actual database file.  Similarly, text-based formats such as Markdown
1228 and AsciiDoc will work better than binary formats such as Microsoft Word and
1229 PDF.</p></div>
1230 <div class="paragraph"><p>Similarly, storing binary dependencies (e.g., shared libraries or JAR files) or
1231 build products in the repository is generally not recommended.  Dependencies and
1232 build products are best stored on an artifact or package server with only
1233 references, URLs, and hashes stored in the repository.</p></div>
1234 <div class="paragraph"><p>We also recommend setting a <a href="gitattributes.html">gitattributes(5)</a> file to explicitly mark
1235 which files are text and which are binary.  If you want Git to guess, you can
1236 set the attribute <code>text=auto</code>.  For example, the following might be appropriate
1237 in some projects:</p></div>
1238 <div class="listingblock">
1239 <div class="content">
1240 <pre><code># By default, guess.
1241 *       text=auto
1242 # Mark all C files as text.
1243 *.c     text
1244 # Mark all JPEG files as binary.
1245 *.jpg   binary</code></pre>
1246 </div></div>
1247 <div class="paragraph"><p>These settings help tools pick the right format for output such as patches and
1248 result in files being checked out in the appropriate line ending for the
1249 platform.</p></div>
1250 </dd>
1251 </dl></div>
1252 </div>
1253 </div>
1254 <div class="sect1">
1255 <h2 id="_git">GIT</h2>
1256 <div class="sectionbody">
1257 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
1258 </div>
1259 </div>
1260 </div>
1261 <div id="footnotes"><hr /></div>
1262 <div id="footer">
1263 <div id="footer-text">
1264 Last updated
1265  2021-09-01 16:44:20 PDT
1266 </div>
1267 </div>
1268 </body>
1269 </html>