| blob | 0fdcae9011f256a1be644c79736d8e93af5e8489 |
5 <head>
10 /* Shared CSS for AsciiDoc xhtml11 and html5 backends */
12 /* Default font. */
13 body {
14 font-family: Georgia,serif;
15 }
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 }
27 body {
29 }
31 a {
32 color: blue;
33 text-decoration: underline;
34 }
35 a:visited {
36 color: fuchsia;
37 }
39 em {
40 font-style: italic;
41 color: navy;
42 }
44 strong {
45 font-weight: bold;
46 color: #083194;
47 }
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 }
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 }
72 div.sectionbody {
73 margin-left: 0;
74 }
76 hr {
77 border: 1px solid silver;
78 }
80 p {
81 margin-top: 0.5em;
82 margin-bottom: 0.5em;
83 }
85 ul, ol, li > p {
86 margin-top: 0;
87 }
88 ul > li { color: #aaa; }
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 }
102 #author {
103 color: #527bbd;
104 font-weight: bold;
105 font-size: 1.1em;
106 }
107 #email {
108 }
109 #revnumber, #revdate, #revremark {
110 }
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 }
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 }
144 div.content { /* Block element content. */
145 padding: 0;
146 }
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 }
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 }
170 div.sidebarblock > div.content {
171 background: #ffffee;
172 border: 1px solid #dddddd;
173 border-left: 4px solid #f0f0f0;
174 padding: 0.5em;
175 }
177 div.listingblock > div.content {
178 border: 1px solid #dddddd;
179 border-left: 5px solid #f0f0f0;
180 background: #f8f8f8;
181 padding: 0.5em;
182 }
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 }
192 div.quoteblock > div.attribution {
193 padding-top: 0.5em;
194 text-align: right;
195 }
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 }
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 }
223 div.exampleblock > div.content {
224 border-left: 3px solid #dddddd;
225 padding-left: 0.5em;
226 }
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; }
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 }
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 }
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 }
272 tfoot {
273 font-weight: bold;
274 }
275 td > div.verse {
276 white-space: pre;
277 }
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 }
303 .comment {
304 background: yellow;
305 }
307 .footnote, .footnoteref {
308 font-size: 0.8em;
309 }
311 span.footnote, span.footnoteref {
312 vertical-align: super;
313 }
315 #footnotes {
318 }
320 #footnotes div.footnote {
322 }
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 }
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 }
343 @media print {
344 #footer-badges { display: none; }
345 }
347 #toc {
348 margin-bottom: 2.5em;
349 }
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 }
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 }
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; }
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; }
410 span.big { font-size: 2em; }
411 span.small { font-size: 0.6em; }
413 span.underline { text-decoration: underline; }
414 span.overline { text-decoration: overline; }
415 span.line-through { text-decoration: line-through; }
417 div.unbreakable { page-break-inside: avoid; }
420 /*
421 * xhtml11 specific
422 *
423 * */
425 div.tableblock {
426 margin-top: 1.0em;
427 margin-bottom: 1.5em;
428 }
429 div.tableblock > table {
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. */
441 border-style: none;
442 }
444 border-left-style: none;
445 border-right-style: none;
446 }
448 border-top-style: none;
449 border-bottom-style: none;
450 }
453 /*
454 * html5 specific
455 *
456 * */
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 }
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 }
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 }
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 }
516 /*
517 * manpage specific
518 *
519 * */
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 }
534 @media print {
535 body.manpage div#toc { display: none; }
536 }
539 </style>
541 /*<![CDATA[*/
542 var asciidoc = { // Namespace.
544 /////////////////////////////////////////////////////////////////////
545 // Table Of Contents generator
546 /////////////////////////////////////////////////////////////////////
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 */
558 /* modified by Troy D. Hanson, September 2006. License: GPL */
562 toc: function (toclevels) {
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 }
575 function TocEntry(el, text, toclevel) {
576 this.element = el;
577 this.text = text;
578 this.toclevel = toclevel;
579 }
581 function tocEntries(el, toclevels) {
582 var result = new Array;
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);
593 }
594 iterate(i);
595 }
596 }
597 }
598 iterate(el);
599 return result;
600 }
602 var toc = document.getElementById("toc");
603 if (!toc) {
604 return;
605 }
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 }
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 },
640 /////////////////////////////////////////////////////////////////////
641 // Footnotes generator
642 /////////////////////////////////////////////////////////////////////
644 /* Based on footnote generation code from:
646 */
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];
659 entriesToRemove.push(entry);
660 }
661 for (i = 0; i < entriesToRemove.length; i++) {
662 noteholder.removeChild(entriesToRemove[i]);
663 }
665 // Rebuild footnote entries.
666 var cont = document.getElementById("content");
667 var spans = cont.getElementsByTagName("span");
668 var refs = {};
669 var n = 0;
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 =
681 spans[i].setAttribute("data-note", note);
682 }
683 noteholder.innerHTML +=
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.
696 if (spans[i].className == "footnoteref") {
698 href = href.match(/#.*/)[0]; // Because IE return full URL.
699 n = refs[href];
700 spans[i].innerHTML =
701 "[<a href='#_footnote_" + n +
703 }
704 }
705 }
706 },
708 install: function(toclevels) {
709 var timerId;
711 function reinstall() {
712 asciidoc.footnotes();
713 if (toclevels) {
714 asciidoc.toc(toclevels);
715 }
716 }
718 function reinstallAndRemoveTimer() {
719 clearInterval(timerId);
720 reinstall();
721 }
723 timerId = setInterval(reinstall, 500);
724 if (document.addEventListener)
725 document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
726 else
727 window.onload = reinstallAndRemoveTimer;
728 }
730 }
731 asciidoc.install();
732 /*]]>*/
733 </script>
734 </head>
737 <h1>
738 gitcore-tutorial(7) Manual Page
739 </h1>
742 <p>gitcore-tutorial -
743 A Git core tutorial for developers
744 </p>
745 </div>
746 </div>
752 </div>
753 </div>
757 <div class="paragraph"><p>This tutorial explains how to use the "core" Git commands to set up and
758 work with a Git repository.</p></div>
759 <div class="paragraph"><p>If you just need to use Git as a revision control system you may prefer
760 to start with "A Tutorial Introduction to Git" (<a href="gittutorial.html">gittutorial(7)</a>) or
765 interfaces on top of it called "porcelain". You may not want to use the
766 plumbing directly very often, but it can be good to know what the
769 commands were shell scripts. For simplicity, it still uses them as
770 examples to illustrate how plumbing is fit together to form the
771 porcelain commands. The source tree includes some of these scripts in
772 contrib/examples/ for reference. Although these are not implemented as
773 shell scripts anymore, the description of what the plumbing layer
774 commands do is still valid.</p></div>
776 <table><tr>
779 </td>
781 skip on your first reading.</td>
782 </tr></table>
783 </div>
784 </div>
785 </div>
789 <div class="paragraph"><p>Creating a new Git repository couldn’t be easier: all Git repositories start
790 out empty, and the only thing you need to do is find yourself a
791 subdirectory that you want to use as a working tree - either an empty
792 one for a totally new project, or an existing working tree that you want
793 to import into Git.</p></div>
794 <div class="paragraph"><p>For our first example, we’re going to start a totally new repository from
796 To start up, create a subdirectory for it, change into that
800 <pre><code>$ mkdir git-tutorial
801 $ cd git-tutorial
802 $ git init</code></pre>
803 </div></div>
808 </div></div>
809 <div class="paragraph"><p>which is just Git’s way of saying that you haven’t been doing anything
813 three entries, among other things:</p></div>
815 <li>
816 <p>
818 This is similar to a symbolic link and points at
820 </p>
821 <div class="paragraph"><p>Don’t worry about the fact that the file that the <code>HEAD</code> link points to
824 </li>
825 <li>
826 <p>
828 objects of your project. You should never have any real reason to
829 look at the objects directly, but you might want to know that these
831 </p>
832 </li>
833 <li>
834 <p>
836 </p>
837 </li>
838 </ul></div>
839 <div class="paragraph"><p>In particular, the <code>refs</code> subdirectory will contain two other
841 exactly what their names imply: they contain references to any number
844 repository.</p></div>
845 <div class="paragraph"><p>One note: the special <code>master</code> head is the default branch, which is
848 point to the branch you are working on right now, and you always
853 valid, though.</p></div>
855 <table><tr>
858 </td>
859 <td class="content">An <em>object</em> is identified by its 160-bit SHA-1 hash, aka <em>object name</em>,
860 and a reference to an object is always the 40-byte hex
862 subdirectory are expected to contain these hex references
864 expect to see a number of 41-byte files containing these
866 populating your tree.</td>
867 </tr></table>
868 </div>
870 <table><tr>
873 </td>
874 <td class="content">An advanced user may want to take a look at <a href="gitrepository-layout.html">gitrepository-layout(5)</a>
875 after finishing this tutorial.</td>
876 </tr></table>
877 </div>
878 <div class="paragraph"><p>You have now created your first Git repository. Of course, since it’s
880 </div>
881 </div>
885 <div class="paragraph"><p>We’ll keep this simple and stupid, so we’ll start off with populating a
886 few trivial files just to get a feel for it.</p></div>
887 <div class="paragraph"><p>Start off with just creating any random files that you want to maintain
888 in your Git repository. We’ll start off with a few bad examples, just to
889 get a feel for how this works:</p></div>
894 </div></div>
895 <div class="paragraph"><p>you have now created two files in your working tree (aka <em>working directory</em>),
896 but to actually check in your hard work, you will have to go through two steps:</p></div>
898 <li>
899 <p>
901 working tree state.
902 </p>
903 </li>
904 <li>
905 <p>
906 commit that index file as an object.
907 </p>
908 </li>
909 </ul></div>
910 <div class="paragraph"><p>The first step is trivial: when you want to tell Git about any changes
912 program normally just takes a list of filenames you want to update, but
913 to avoid trivial mistakes, it refuses to add new entries to the index
914 (or remove existing ones) unless you explicitly tell it that you’re
917 <div class="paragraph"><p>So to populate the index with the two files you just created, you can do</p></div>
921 </div></div>
924 you’ll notice that Git will have added two new objects to the object
925 database. If you did exactly the steps above, you should now be able to do</p></div>
929 </div></div>
935 </div></div>
936 <div class="paragraph"><p>which correspond with the objects with names of <code>557db...</code> and
938 <div class="paragraph"><p>If you want to, you can use <em>git cat-file</em> to look at those objects, but
943 </div></div>
944 <div class="paragraph"><p>where the <code>-t</code> tells <em>git cat-file</em> to tell you what the "type" of the
945 object is. Git will tell you that you have a "blob" object (i.e., just a
946 regular file), and you can see the contents with</p></div>
950 </div></div>
951 <div class="paragraph"><p>which will print out "Hello World". The object <code>557db03</code> is nothing
954 <table><tr>
957 </td>
958 <td class="content">Don’t confuse that object with the file <code>hello</code> itself. The
961 we just looked at will never change. Objects are immutable.</td>
962 </tr></table>
963 </div>
965 <table><tr>
968 </td>
970 abbreviate the object name to only the first several
971 hexadecimal digits in most places.</td>
972 </tr></table>
973 </div>
974 <div class="paragraph"><p>Anyway, as we mentioned previously, you normally never actually take a
975 look at the objects themselves, and typing long 40-character hex
976 names is not something you’d normally want to do. The above digression
978 actually saved away the contents of your files into the Git object
979 database.</p></div>
980 <div class="paragraph"><p>Updating the index did something else too: it created a <code>.git/index</code>
981 file. This is the index that describes your current working tree, and
982 something you should be very aware of. Again, you normally never worry
983 about the index file itself, but you should be aware of the fact that
984 you have not actually really "checked in" your files into Git so far,
986 <div class="paragraph"><p>However, since Git knows about them, you can now start using some of the
987 most basic Git commands to manipulate the files or look at their status.</p></div>
988 <div class="paragraph"><p>In particular, let’s not even check in the two files into Git yet, we’ll
993 </div></div>
994 <div class="paragraph"><p>and you can now, since you told Git about the previous state of <code>hello</code>, ask
995 Git what has changed in the tree compared to your old index, using the
1000 </div></div>
1001 <div class="paragraph"><p>Oops. That wasn’t very readable. It just spit out its own internal
1003 that it has noticed that "hello" has been modified, and that the old object
1004 contents it had have been replaced with something else.</p></div>
1005 <div class="paragraph"><p>To make it readable, we can tell <em>git diff-files</em> to output the
1009 <pre><code>$ git diff-files -p
1010 diff --git a/hello b/hello
1012 --- a/hello
1013 +++ b/hello
1015 Hello World
1016 +It's a new day for git</code></pre>
1017 </div></div>
1018 <div class="paragraph"><p>i.e. the diff of the change we caused by adding another line to <code>hello</code>.</p></div>
1019 <div class="paragraph"><p>In other words, <em>git diff-files</em> always shows us the difference between
1020 what is recorded in the index, and what is currently in the working
1022 <div class="paragraph"><p>A common shorthand for <code>git diff-files -p</code> is to just write <code>git
1026 <pre><code>$ git diff
1027 diff --git a/hello b/hello
1029 --- a/hello
1030 +++ b/hello
1032 Hello World
1033 +It's a new day for git</code></pre>
1034 </div></div>
1035 </div>
1036 </div>
1040 <div class="paragraph"><p>Now, we want to go to the next stage in Git, which is to take the files
1041 that Git knows about in the index, and commit them as a real tree. We do
1044 tree was all about, along with information of how we came to that state.</p></div>
1045 <div class="paragraph"><p>Creating a tree object is trivial, and is done with <em>git write-tree</em>.
1047 current index state, and write an object that describes that whole
1048 index. In other words, we’re now tying together all the different
1049 filenames with their contents (and their permissions), and we’re
1054 </div></div>
1055 <div class="paragraph"><p>and this will just output the name of the resulting tree, in this case
1060 </div></div>
1061 <div class="paragraph"><p>which is another incomprehensible object name. Again, if you want to,
1066 <div class="paragraph"><p>However — normally you’d never use <em>git write-tree</em> on its own, because
1067 normally you always commit a tree into a commit object using the
1071 <div class="paragraph"><p><em>git commit-tree</em> normally takes several arguments — it wants to know
1073 ever in this new repository, and it has no parents, we only need to pass in
1075 commit message on its standard input, and it will write out the resulting
1076 object name for the commit to its standard output.</p></div>
1077 <div class="paragraph"><p>And this is where we create the <code>.git/refs/heads/master</code> file
1079 the reference to the top-of-tree of the master branch, and since
1081 all with a sequence of simple shell commands:</p></div>
1084 <pre><code>$ tree=$(git write-tree)
1085 $ commit=$(echo 'Initial commit' | git commit-tree $tree)
1086 $ git update-ref HEAD $commit</code></pre>
1087 </div></div>
1088 <div class="paragraph"><p>In this case this creates a totally new commit that is not related to
1090 all later commits will be parented on top of an earlier commit.</p></div>
1091 <div class="paragraph"><p>Again, normally you’d never actually do this by hand. There is a
1094 instead, and it would have done the above magic scripting for you.</p></div>
1095 </div>
1096 </div>
1100 <div class="paragraph"><p>Remember how we did the <em>git update-index</em> on file <code>hello</code> and then we
1101 changed <code>hello</code> afterward, and could compare the new state of <code>hello</code> with the
1102 state we saved in the index file?</p></div>
1103 <div class="paragraph"><p>Further, remember how I said that <em>git write-tree</em> writes the contents
1105 fact the <strong>original</strong> contents of the file <code>hello</code>, not the new ones. We did
1106 that on purpose, to show the difference between the index state, and the
1107 state in the working tree, and how they don’t have to match, even
1108 when we commit things.</p></div>
1109 <div class="paragraph"><p>As before, if we do <code>git diff-files -p</code> in our git-tutorial project,
1110 we’ll still see the same difference we saw last time: the index file
1111 hasn’t changed by the act of committing anything. However, now that we
1112 have committed something, we can also learn to use a new command:
1114 <div class="paragraph"><p>Unlike <em>git diff-files</em>, which showed the difference between the index
1118 against, and before we did the commit, we couldn’t do that, because we
1124 </div></div>
1125 <div class="paragraph"><p>(where <code>-p</code> has the same meaning as it did in <em>git diff-files</em>), and it
1126 will show us the same difference, but for a totally different reason.
1127 Now we’re comparing the working tree not against the index file,
1128 but against the tree we just wrote. It just so happens that those two
1129 are obviously the same, so we get the same result.</p></div>
1130 <div class="paragraph"><p>Again, because this is a common operation, you can also just shorthand
1131 it with</p></div>
1135 </div></div>
1137 <div class="paragraph"><p>In other words, <em>git diff-index</em> normally compares a tree against the
1139 instead compare against just the index cache contents, and ignore the
1140 current working tree state entirely. Since we just wrote the index
1144 <table><tr>
1147 </td>
1150 comparisons, and saying that it compares a tree against the working
1151 tree is thus not strictly accurate. In particular, the list of
1155 come from the working tree or not.</p></div>
1156 <div class="paragraph"><p>This is not hard to understand, as soon as you realize that Git simply
1157 never knows (or cares) about files that it is not told about
1159 expects you to tell it what the files are, and that’s what the index
1160 is there for.</p></div>
1161 </td>
1162 </tr></table>
1163 </div>
1164 <div class="paragraph"><p>However, our next step is to commit the <strong>change</strong> we did, and again, to
1167 in the working tree that we want to commit, and we always have to
1168 work through the index file, so the first thing we need to do is to
1169 update the index cache:</p></div>
1173 </div></div>
1174 <div class="paragraph"><p>(note how we didn’t need the <code>--add</code> flag this time, since Git knew
1175 about the file already).</p></div>
1176 <div class="paragraph"><p>Note what happens to the different <em>git diff-*</em> versions here.
1177 After we’ve updated <code>hello</code> in the index, <code>git diff-files -p</code> now shows no
1179 current state is different from the state we committed. In fact, now
1181 flag or not, since now the index is coherent with the working tree.</p></div>
1182 <div class="paragraph"><p>Now, since we’ve updated <code>hello</code> in the index, we can commit the new
1183 version. We could do it by writing the tree by hand again, and
1191 </div></div>
1192 <div class="paragraph"><p>which starts an editor for you to write the commit message and tells you
1193 a bit about what you have done.</p></div>
1194 <div class="paragraph"><p>Write whatever message you want, and all the lines that start with <em>#</em>
1195 will be pruned out, and the rest will be used as the commit message for
1196 the change. If you decide you don’t want to commit anything after all at
1197 this point (you can continue to edit things and update the index), you
1199 the change for you.</p></div>
1200 <div class="paragraph"><p>You’ve now made your first real Git commit. And if you’re interested in
1202 it’s a few very simple shell scripts to generate the helpful (?) commit
1203 message headers, and a few one-liners that actually do the
1205 </div>
1206 </div>
1210 <div class="paragraph"><p>While creating changes is useful, it’s even more useful if you can tell
1211 later what changed. The most useful command for this is another of the
1213 <div class="paragraph"><p><em>git diff-tree</em> can be given two arbitrary trees, and it will tell you the
1214 differences between them. Perhaps even more commonly, though, you can
1215 give it just a single commit object, and it will figure out the parent
1216 of that commit itself, and show the difference directly. Thus, to get
1221 </div></div>
1222 <div class="paragraph"><p>(again, <code>-p</code> means to show the difference as a human-readable patch),
1225 <table><tr>
1228 </td>
1234 <pre><code> diff-tree
1235 +----+
1236 | |
1237 | |
1238 V V
1239 +-----------+
1240 | Object DB |
1241 | Backing |
1242 | Store |
1243 +-----------+
1244 ^ ^
1245 | |
1246 | | diff-index --cached
1247 | |
1248 diff-index | V
1249 | +-----------+
1250 | | Index |
1251 | | "cache" |
1252 | +-----------+
1253 | ^
1254 | |
1255 | | diff-files
1256 | |
1257 V V
1258 +-----------+
1259 | Working |
1260 | Directory |
1261 +-----------+</code></pre>
1262 </div></div>
1263 </td>
1264 </tr></table>
1265 </div>
1266 <div class="paragraph"><p>More interestingly, you can also give <em>git diff-tree</em> the <code>--pretty</code> flag,
1267 which tells it to also show the commit message and author and date of the
1268 commit, and you can tell it to show a whole series of diffs.
1269 Alternatively, you can tell it to be "silent", and not show the diffs at
1270 all, but just show the actual commit message.</p></div>
1271 <div class="paragraph"><p>In fact, together with the <em>git rev-list</em> program (which generates a
1274 script that pipes the output of <code>git rev-list</code> to <code>git diff-tree --stdin</code>,
1276 </div>
1277 </div>
1281 <div class="paragraph"><p>In Git, there are two kinds of tags, a "light" one, and an "annotated tag".</p></div>
1282 <div class="paragraph"><p>A "light" tag is technically nothing more than a branch, except we put
1284 So the simplest form of tag involves nothing more than</p></div>
1288 </div></div>
1289 <div class="paragraph"><p>which just writes the current <code>HEAD</code> into the <code>.git/refs/tags/my-first-tag</code>
1290 file, after which point you can then use this symbolic name for that
1291 particular state. You can, for example, do</p></div>
1295 </div></div>
1297 obviously be an empty diff, but if you continue to develop and commit
1298 stuff, you can use your tag as an "anchor-point" to see what has changed
1299 since you tagged it.</p></div>
1300 <div class="paragraph"><p>An "annotated tag" is actually a real Git object, and contains not only a
1301 pointer to the state you want to tag, but also a small tag name and
1302 message, along with optionally a PGP signature that says that yes,
1303 you really did
1309 </div></div>
1310 <div class="paragraph"><p>which will sign the current <code>HEAD</code> (but you can also give it another
1311 argument that specifies the thing to tag, e.g., you could have tagged the
1312 current <code>mybranch</code> point by using <code>git tag <tagname> mybranch</code>).</p></div>
1314 like that, while the light-weight tags are useful for any marking you
1315 want to do — any time you decide that you want to remember a certain
1316 point, just create a private tag for it, and you have a nice symbolic
1317 name for the state at that point.</p></div>
1318 </div>
1319 </div>
1323 <div class="paragraph"><p>Git repositories are normally totally self-sufficient and relocatable.
1324 Unlike CVS, for example, there is no separate notion of
1327 subdirectory. There is nothing else. What you see is what you got.</p></div>
1329 <table><tr>
1332 </td>
1335 how normal projects work, and it’s really only meant for special uses.
1336 So the mental model of "the Git information is always tied directly to
1339 </tr></table>
1340 </div>
1343 <li>
1344 <p>
1345 if you grow bored with the tutorial repository you created (or you’ve
1346 made a mistake and want to start all over), you can just do simple
1347 </p>
1351 </div></div>
1352 <div class="paragraph"><p>and it will be gone. There’s no external repository, and there’s no
1353 history outside the project you created.</p></div>
1354 </li>
1355 <li>
1356 <p>
1357 if you want to move or duplicate a Git repository, you can do so. There
1359 create a copy of your repository (with all the full history that
1360 went along with it), you can do so with a regular
1362 </p>
1363 <div class="paragraph"><p>Note that when you’ve moved or copied a Git repository, your Git index
1364 file (which caches various information, notably some of the "stat"
1365 information for the files involved) will likely need to be refreshed.
1370 </div></div>
1371 <div class="paragraph"><p>in the new repository to make sure that the index file is up to date.</p></div>
1372 </li>
1373 </ul></div>
1377 <div class="paragraph"><p>When copying a remote repository, you’ll want to at a minimum update the
1378 index cache when you do this, and especially with other peoples'
1379 repositories you often want to make sure that the index cache is in some
1380 known state (you don’t know <strong>what</strong> they’ve done and not yet checked in),
1384 <pre><code>$ git read-tree --reset HEAD
1385 $ git update-index --refresh</code></pre>
1386 </div></div>
1387 <div class="paragraph"><p>which will force a total index re-build from the tree pointed to by <code>HEAD</code>.
1389 makes sure to match up all index entries with the checked-out files.
1390 If the original repository had uncommitted changes in its
1392 tells you they need to be updated.</p></div>
1397 </div></div>
1398 <div class="paragraph"><p>and in fact a lot of the common Git command combinations can be scripted
1403 the basic Git commands.</p></div>
1406 actual core Git files. Such a repository usually doesn’t even have the
1408 repository.</p></div>
1409 <div class="paragraph"><p>To create your own local live copy of such a "raw" Git repository, you’d
1410 first create your own subdirectory for the project, and then copy the
1415 <pre><code>$ mkdir my-git
1416 $ cd my-git
1417 $ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git</code></pre>
1418 </div></div>
1423 </div></div>
1424 <div class="paragraph"><p>to populate the index. However, now you have populated the index, and
1425 you have all the Git internal files, but you will notice that you don’t
1426 actually have any of the working tree files to work on. To get
1431 </div></div>
1432 <div class="paragraph"><p>where the <code>-u</code> flag means that you want the checkout to keep the index
1433 up to date (so that you don’t have to refresh it afterward), and the
1436 flag first, to tell <em>git checkout-index</em> to <strong>force</strong> overwriting of any old
1437 files).</p></div>
1441 <pre><code>$ git clone git://git.kernel.org/pub/scm/git/git.git/ my-git
1442 $ cd my-git
1443 $ git checkout</code></pre>
1444 </div></div>
1447 repository, and checked it out.</p></div>
1448 </div>
1449 </div>
1456 these object pointers.</p></div>
1458 point in the project history, and just writing the SHA-1 name of that
1460 want (and indeed, subdirectories), but the convention is that the
1462 and nothing enforces it.</p></div>
1463 <div class="paragraph"><p>To show that as an example, let’s go back to the git-tutorial repository we
1464 used earlier, and create a branch in it. You do that by simply just
1465 saying that you want to check out a new branch:</p></div>
1469 </div></div>
1470 <div class="paragraph"><p>will create a new branch based at the current <code>HEAD</code> position, and switch
1471 to it.</p></div>
1473 <table><tr>
1476 </td>
1485 </div></div>
1486 <div class="paragraph"><p>and it would create the new branch <code>mybranch</code> at the earlier commit,
1487 and check out the state at that time.</p></div>
1488 </td>
1489 </tr></table>
1490 </div>
1491 <div class="paragraph"><p>You can always just jump back to your original <code>master</code> branch by doing</p></div>
1495 </div></div>
1497 branch you happen to be on, a simple</p></div>
1501 </div></div>
1503 you have, you can say</p></div>
1507 </div></div>
1508 <div class="paragraph"><p>which used to be nothing more than a simple script around <code>ls .git/refs/heads</code>.
1509 There will be an asterisk in front of the branch you are currently on.</p></div>
1510 <div class="paragraph"><p>Sometimes you may wish to create a new branch <em>without</em> actually
1511 checking it out and switching to it. If so, just use the command</p></div>
1515 </div></div>
1516 <div class="paragraph"><p>which will simply <em>create</em> the branch, but will not do anything further.
1517 You can then later — once you decide that you want to actually develop
1519 with the branchname as the argument.</p></div>
1520 </div>
1521 </div>
1526 experimental) work in it, and eventually merge it back to the main
1528 being the same as the original <code>master</code> branch, let’s make sure we’re in
1529 that branch, and do some work there.</p></div>
1532 <pre><code>$ git switch mybranch
1535 </div></div>
1536 <div class="paragraph"><p>Here, we just added another line to <code>hello</code>, and we used a shorthand for
1541 commit log message from the command line.</p></div>
1542 <div class="paragraph"><p>Now, to make it a bit more interesting, let’s assume that somebody else
1543 does some work in the original branch, and simulate that by going back
1544 to the master branch, and editing the same file differently there:</p></div>
1548 </div></div>
1549 <div class="paragraph"><p>Here, take a moment to look at the contents of <code>hello</code>, and notice how they
1550 don’t contain the work we just did in <code>mybranch</code> — because that work
1557 </div></div>
1558 <div class="paragraph"><p>since the master branch is obviously in a much better mood.</p></div>
1559 <div class="paragraph"><p>Now, you’ve got two branches, and you decide that you want to merge the
1560 work done. Before we do that, let’s introduce a cool graphical tool that
1565 </div></div>
1566 <div class="paragraph"><p>will show you graphically both of your branches (that’s what the <code>--all</code>
1568 histories. You can also see exactly how they came to be from a common
1569 source.</p></div>
1570 <div class="paragraph"><p>Anyway, let’s exit <em>gitk</em> (<code>^Q</code> or the File menu), and decide that we want
1574 to resolve and what the merge is all about:</p></div>
1578 </div></div>
1579 <div class="paragraph"><p>where the first argument is going to be used as the commit message if
1580 the merge can be resolved automatically.</p></div>
1581 <div class="paragraph"><p>Now, in this case we’ve intentionally created a situation where the
1582 merge will need to be fixed up by hand, though, so Git will do as much
1587 <pre><code> Auto-merging hello
1588 CONFLICT (content): Merge conflict in hello
1589 Automatic merge failed; fix conflicts and then commit the result.</code></pre>
1590 </div></div>
1593 <div class="paragraph"><p>Not to worry. It left the (trivial) conflict in <code>hello</code> in the same form you
1599 <pre><code>Hello World
1600 It's a new day for git
1601 Play, play, play
1602 Work, work, work</code></pre>
1603 </div></div>
1604 <div class="paragraph"><p>and once you’re happy with your manual merge, just do a</p></div>
1608 </div></div>
1609 <div class="paragraph"><p>which will very loudly warn you that you’re now committing a merge
1610 (which is correct, so never mind), and you can write a small merge
1612 <div class="paragraph"><p>After you’re done, start up <code>gitk --all</code> to see graphically what the
1614 switch to it, and continue to work with it if you want to. The
1618 <div class="paragraph"><p>Another useful tool, especially if you do not always work in X-Window
1623 * [master] Merge work in mybranch
1624 ! [mybranch] Some work.
1625 --
1626 - [master] Merge work in mybranch
1627 *+ [mybranch] Some work.
1628 * [master^] Some fun.</code></pre>
1629 </div></div>
1631 with the titles of their top-of-the-tree commits, you are currently on
1633 column for the later output lines is used to show commits contained in the
1635 branch. Three commits are shown along with their titles.
1641 commits from the master branch. The string inside brackets
1642 before the commit log message is a short name you can use to
1646 see more complex cases.</p></div>
1648 <table><tr>
1651 </td>
1652 <td class="content">Without the <em>--more=1</em> option, <em>git show-branch</em> would not output the
1654 both <em>master</em> and <em>mybranch</em> tips. Please see <a href="git-show-branch.html">git-show-branch(1)</a>
1655 for details.</td>
1656 </tr></table>
1657 </div>
1659 <table><tr>
1662 </td>
1663 <td class="content">If there were more commits on the <em>master</em> branch after the merge, the
1666 merge commit visible in this case.</td>
1667 </tr></table>
1668 </div>
1675 <pre><code>$ git switch mybranch
1677 </div></div>
1679 would be different)</p></div>
1682 <pre><code>Updating from ae3a2da... to a80b4aa....
1683 Fast-forward (no commit created; -m option ignored)
1684 example | 1 +
1685 hello | 1 +
1687 </div></div>
1690 not actually do a merge. Instead, it just updated the top of
1693 <div class="paragraph"><p>You can run <code>gitk --all</code> again to see how the commit ancestry
1697 <pre><code>$ git show-branch master mybranch
1698 ! [master] Merge work in mybranch
1699 * [mybranch] Merge work in mybranch
1700 --
1701 -- [master] Merge work in mybranch</code></pre>
1702 </div></div>
1703 </div>
1704 </div>
1708 <div class="paragraph"><p>It’s usually much more common that you merge with somebody else than
1709 merging with your own branches, so it’s worth pointing out that Git
1710 makes that very easy too, and in fact, it’s not that different from
1712 more than "fetch the work from a remote repository into a temporary tag"
1719 </div></div>
1721 repository to download from:</p></div>
1724 SSH
1725 </dt>
1726 <dd>
1727 <p>
1729 </p>
1733 remote machine. It finds out the set of objects the other side
1734 lacks by exchanging the head commits both ends have and
1735 transfers (close to) minimum set of objects. It is by far the
1736 most efficient way to exchange Git objects between repositories.</p></div>
1737 </dd>
1739 Local directory
1740 </dt>
1741 <dd>
1742 <p>
1744 </p>
1745 <div class="paragraph"><p>This transport is the same as SSH transport but uses <em>sh</em> to run
1746 both ends on the local machine instead of running other end on
1748 </dd>
1750 Git Native
1751 </dt>
1752 <dd>
1753 <p>
1755 </p>
1757 transport, it finds out the set of objects the downstream side
1758 lacks and transfers (close to) minimum set of objects.</p></div>
1759 </dd>
1761 HTTP(S)
1762 </dt>
1763 <dd>
1764 <p>
1766 </p>
1768 first obtains the topmost commit object name from the remote site
1770 and then tries to obtain the
1772 using the object name of that commit object. Then it reads the
1773 commit object to find out its parent commits and the associate
1774 tree object; it repeats this process until it gets all the
1775 necessary objects. Because of this behavior, they are
1778 transports</em>, because they do not require any Git aware smart
1779 server like Git Native transport does. Any stock HTTP server
1780 that does not even support directory index would suffice. But
1782 to help dumb transport downloaders.</p></div>
1783 </dd>
1784 </dl></div>
1785 <div class="paragraph"><p>Once you fetch from the remote repository, you <code>merge</code> that
1786 with your current branch.</p></div>
1787 <div class="paragraph"><p>However — it’s such a common thing to <code>fetch</code> and then
1789 simply do</p></div>
1793 </div></div>
1795 argument.</p></div>
1797 <table><tr>
1800 </td>
1802 keeping as many local repositories as you would like to have
1804 you merge between branches. The advantage of this approach is
1806 out and you may find it easier to switch back and forth if you
1807 juggle multiple lines of development simultaneously. Of
1808 course, you will pay the price of more disk usage to hold
1809 multiple working trees, but disk space is cheap these days.</td>
1810 </tr></table>
1811 </div>
1813 repository from time to time. As a short hand, you can store
1814 the remote repository URL in the local repository’s config file
1815 like this:</p></div>
1818 <pre><code>$ git config remote.linus.url https://git.kernel.org/pub/scm/git/git.git/</code></pre>
1819 </div></div>
1820 <div class="paragraph"><p>and use the "linus" keyword with <em>git pull</em> instead of the full URL.</p></div>
1823 <li>
1824 <p>
1826 </p>
1827 </li>
1828 <li>
1829 <p>
1831 </p>
1832 </li>
1833 </ol></div>
1836 <li>
1837 <p>
1839 </p>
1840 </li>
1841 <li>
1842 <p>
1844 </p>
1845 </li>
1846 </ol></div>
1847 </div>
1848 </div>
1853 with the porcelain that isn’t flushing, but we so far did not
1854 talk about how the merge really works. If you are following
1859 and bring ourselves back to the pre-merge state:</p></div>
1863 ! [master] Merge work in mybranch
1864 * [mybranch] Merge work in mybranch
1865 --
1866 -- [master] Merge work in mybranch
1867 +* [master^2] Some work.
1868 +* [master^] Some fun.</code></pre>
1869 </div></div>
1870 <div class="paragraph"><p>Remember, before running <em>git merge</em>, our <code>master</code> head was at
1876 $ git switch master
1877 $ git reset --hard master^</code></pre>
1878 </div></div>
1879 <div class="paragraph"><p>After rewinding, the commit structure should look like this:</p></div>
1882 <pre><code>$ git show-branch
1883 * [master] Some fun.
1884 ! [mybranch] Some work.
1885 --
1886 * [master] Some fun.
1887 + [mybranch] Some work.
1888 *+ [master^] Initial commit</code></pre>
1889 </div></div>
1891 <div class="paragraph"><p><code>git merge</code> command, when merging two branches, uses 3-way merge
1892 algorithm. First, it finds the common ancestor between them.
1897 </div></div>
1899 to the standard output, so we captured its output to a variable,
1900 because we will be using it in the next step. By the way, the common
1901 ancestor commit is the "Initial commit" commit in this case. You can
1902 tell it by:</p></div>
1905 <pre><code>$ git name-rev --name-only --tags $mb
1906 my-first-tag</code></pre>
1907 </div></div>
1909 this:</p></div>
1913 </div></div>
1914 <div class="paragraph"><p>This is the same <em>git read-tree</em> command we have already seen,
1915 but it takes three trees, unlike previous examples. This reads
1918 etc.). After reading three trees into three stages, the paths
1920 0. Also paths that are the same in two of three stages are
1923 changed from the common ancestor).</p></div>
1924 <div class="paragraph"><p>After <em>collapsing</em> operation, paths that are different in three
1925 trees are left in non-zero stages. At this point, you can
1926 inspect the index file with this command:</p></div>
1929 <pre><code>$ git ls-files --stage
1934 </div></div>
1937 large projects, when only a small number of files change in one commit,
1939 fairly quickly, leaving only a handful of real changes in non-zero
1940 stages.</p></div>
1941 <div class="paragraph"><p>To look at only non-zero stages, use <code>--unmerged</code> flag:</p></div>
1944 <pre><code>$ git ls-files --unmerged
1948 </div></div>
1950 file, using 3-way merge. This is done by giving
1955 <pre><code>$ git merge-index git-merge-one-file hello
1956 Auto-merging hello
1957 ERROR: Merge conflict in hello
1958 fatal: merge program failed</code></pre>
1959 </div></div>
1961 describe those three versions, and is responsible to leave the
1962 merge results in the working tree.
1963 It is a fairly straightforward shell script, and
1966 conflicts, and the merge result with conflict marks is left in
1967 the working tree.. This can be seen if you run <code>ls-files
1971 <pre><code>$ git ls-files --stage
1976 </div></div>
1982 </div>
1983 </div>
1987 <div class="paragraph"><p>So, we can use somebody else’s work from a remote repository, but
1989 it?</p></div>
1993 people to pull from it, but in practice that is not the way
1994 things are usually done. A recommended way is to have a public
1995 repository, make it reachable by other people, and when the
1996 changes you made in your primary working tree are in good shape,
1997 update the public repository from it. This is often called
2000 <table><tr>
2003 </td>
2006 </tr></table>
2007 </div>
2009 your remote (public) repository requires a write privilege on
2010 the remote machine. You need to have an SSH account there to
2013 machine that will house your public repository. This empty
2014 repository will be populated and be kept up to date by pushing
2015 into it later. Obviously, this repository creation needs to be
2016 done only once.</p></div>
2018 <table><tr>
2021 </td>
2024 on the remote machine. The communication between the two over
2025 the network internally uses an SSH connection.</td>
2026 </tr></table>
2027 </div>
2028 <div class="paragraph"><p>Your private repository’s Git directory is usually <code>.git</code>, but
2029 your public repository is often named after the project name,
2032 an empty directory:</p></div>
2036 </div></div>
2043 </div></div>
2045 changes to be pulled via the transport of your choice. Also
2049 <table><tr>
2052 </td>
2054 shell when you directly run programs; what this means is that if
2058 </tr></table>
2059 </div>
2061 <table><tr>
2064 </td>
2066 you should do <code>mv my-git.git/hooks/post-update.sample
2067 my-git.git/hooks/post-update</code> at this point.
2068 This makes sure that every time you push into this
2070 </tr></table>
2071 </div>
2073 Come back to the machine you have your private repository. From
2074 there, run this command:</p></div>
2078 </div></div>
2081 from them in your current repository.</p></div>
2083 repository. Kernel.org mirror network takes care of the
2084 propagation to other publicly visible machines:</p></div>
2088 </div></div>
2089 </div>
2090 </div>
2094 <div class="paragraph"><p>Earlier, we saw that one file under <code>.git/objects/??/</code> directory
2095 is stored for each Git object you create. This representation
2096 is efficient to create atomically and safely, but
2097 not so convenient to transport over the network. Since Git objects are
2098 immutable once they are created, there is a way to optimize the
2103 </div></div>
2108 directory.</p></div>
2110 <table><tr>
2113 </td>
2114 <td class="content">You will see two files, <code>pack-*.pack</code> and <code>pack-*.idx</code>,
2116 each other, and if you ever copy them by hand to a different
2117 repository for whatever reason, you should make sure you copy
2118 them together. The former holds all the data from the objects
2119 in the pack, and the latter holds the index for random
2120 access.</td>
2121 </tr></table>
2122 </div>
2124 detect if you have a corrupt pack, but do not worry too much.
2125 Our programs are always perfect ;-).</p></div>
2127 unpacked objects that are contained in the pack file anymore.</p></div>
2131 </div></div>
2133 <div class="paragraph"><p>You can try running <code>find .git/objects -type f</code> before and after
2135 count-objects</code> would tell you how many unpacked objects are in
2136 your repository and how much space they are consuming.</p></div>
2138 <table><tr>
2141 </td>
2143 packed repository may contain relatively few objects in a
2144 relatively large pack. If you expect many HTTP pulls from your
2145 public repository you might want to repack & prune often, or
2146 never.</td>
2147 </tr></table>
2148 </div>
2150 "Nothing new to pack.". Once you continue your development and
2152 new pack, that contains objects created since you packed your
2153 repository the last time. We recommend that you pack your project
2154 soon after the initial import (unless you are starting your
2156 while, depending on how active your project is.</p></div>
2157 <div class="paragraph"><p>When a repository is synchronized via <code>git push</code> and <code>git pull</code>
2158 objects packed in the source repository are usually stored
2159 unpacked in the destination.
2160 While this allows you to use different packing strategies on
2161 both ends, it also means you may need to repack both
2162 repositories every once in a while.</p></div>
2163 </div>
2164 </div>
2169 convenient to organize your project with an informal hierarchy
2170 of developers. Linux kernel development is run this way. There
2172 <a href="https://web.archive.org/web/20120915203609/http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf">Randy Dunlap’s presentation</a>.</p></div>
2173 <div class="paragraph"><p>It should be stressed that this hierarchy is purely <strong>informal</strong>.
2174 There is nothing fundamental in Git that enforces the "chain of
2175 patch flow" this hierarchy implies. You do not have to pull
2176 from only one remote repository.</p></div>
2177 <div class="paragraph"><p>A recommended workflow for a "project lead" goes like this:</p></div>
2179 <li>
2180 <p>
2181 Prepare your primary repository on your local machine. Your
2182 work is done there.
2183 </p>
2184 </li>
2185 <li>
2186 <p>
2187 Prepare a public repository accessible to others.
2188 </p>
2190 transport protocols (HTTP), you need to keep this repository
2194 but you need to manually enable the hook with
2197 </li>
2198 <li>
2199 <p>
2200 Push into the public repository from your primary
2201 repository.
2202 </p>
2203 </li>
2204 <li>
2205 <p>
2207 pack that contains the initial set of objects as the
2209 used for pulling from your repository supports packed
2210 repositories.
2211 </p>
2212 </li>
2213 <li>
2214 <p>
2215 Keep working in your primary repository. Your changes
2216 include modifications of your own, patches you receive via
2217 e-mails, and merges resulting from pulling the "public"
2218 repositories of your "subsystem maintainers".
2219 </p>
2220 <div class="paragraph"><p>You can repack this private repository whenever you feel like.</p></div>
2221 </li>
2222 <li>
2223 <p>
2224 Push your changes to the public repository, and announce it
2225 to the public.
2226 </p>
2227 </li>
2228 <li>
2229 <p>
2231 Go back to step 5. and continue working.
2232 </p>
2233 </li>
2234 </ol></div>
2238 <li>
2239 <p>
2241 repository of the "project lead". The URL used for the
2242 initial cloning is stored in the remote.origin.url
2243 configuration variable.
2244 </p>
2245 </li>
2246 <li>
2247 <p>
2248 Prepare a public repository accessible to others, just like
2249 the "project lead" person does.
2250 </p>
2251 </li>
2252 <li>
2253 <p>
2254 Copy over the packed files from "project lead" public
2255 repository to your public repository, unless the "project
2256 lead" repository lives on the same machine as yours. In the
2258 point at the repository you are borrowing from.
2259 </p>
2260 </li>
2261 <li>
2262 <p>
2263 Push into the public repository from your primary
2265 transport used for pulling from your repository supports
2266 packed repositories.
2267 </p>
2268 </li>
2269 <li>
2270 <p>
2271 Keep working in your primary repository. Your changes
2272 include modifications of your own, patches you receive via
2273 e-mails, and merges resulting from pulling the "public"
2274 repositories of your "project lead" and possibly your
2275 "sub-subsystem maintainers".
2276 </p>
2278 like.</p></div>
2279 </li>
2280 <li>
2281 <p>
2282 Push your changes to your public repository, and ask your
2284 maintainers" to pull from it.
2285 </p>
2286 </li>
2287 <li>
2288 <p>
2290 Go back to step 5. and continue working.
2291 </p>
2292 </li>
2293 </ol></div>
2295 not have a "public" repository is somewhat different. It goes
2296 like this:</p></div>
2298 <li>
2299 <p>
2302 maintainer", if you work on a subsystem). The URL used for
2303 the initial cloning is stored in the remote.origin.url
2304 configuration variable.
2305 </p>
2306 </li>
2307 <li>
2308 <p>
2310 </p>
2311 </li>
2312 <li>
2313 <p>
2315 upstream every once in a while. This does only the first
2318 </p>
2319 </li>
2320 <li>
2321 <p>
2324 unmerged changes forward to the updated upstream.
2325 </p>
2326 </li>
2327 <li>
2328 <p>
2330 submission to your upstream and send it out. Go back to
2331 step 2. and continue.
2332 </p>
2333 </li>
2334 </ol></div>
2335 </div>
2336 </div>
2338 <h2 id="_working_with_others_shared_repository_style">Working with Others, Shared Repository Style</h2>
2341 suggested in the previous section may be new to you. You do not
2342 have to worry. Git supports the "shared public repository" style of
2343 cooperation you are probably more familiar with as well.</p></div>
2344 <div class="paragraph"><p>See <a href="gitcvs-migration.html">gitcvs-migration(7)</a> for the details.</p></div>
2345 </div>
2346 </div>
2351 a time. It is easy to manage those more-or-less independent tasks
2352 using branches with Git.</p></div>
2354 with "fun and work" example using two branches. The idea is the
2355 same if there are more than two branches. Let’s say you started
2357 branch, and two independent fixes in the "commit-fix" and
2361 <pre><code>$ git show-branch
2362 ! [commit-fix] Fix commit message normalization.
2363 ! [diff-fix] Fix rename detection.
2364 * [master] Release candidate #1
2365 ---
2366 + [diff-fix] Fix rename detection.
2367 + [diff-fix~1] Better common substring algorithm.
2368 + [commit-fix] Fix commit message normalization.
2369 * [master] Release candidate #1
2371 </div></div>
2379 </div></div>
2383 <pre><code>$ git show-branch
2384 ! [commit-fix] Fix commit message normalization.
2385 ! [diff-fix] Fix rename detection.
2386 * [master] Merge fix in commit-fix
2387 ---
2388 - [master] Merge fix in commit-fix
2389 + * [commit-fix] Fix commit message normalization.
2390 - [master~1] Merge fix in diff-fix
2391 +* [diff-fix] Fix rename detection.
2392 +* [diff-fix~1] Better common substring algorithm.
2395 </div></div>
2397 first and the other next, when what you have are a set of truly
2398 independent changes (if the order mattered, then they are not
2399 independent by definition). You could instead merge those two
2400 branches into the current branch at once. First let’s undo what
2401 we just did and start over. We would want to get the master
2406 </div></div>
2407 <div class="paragraph"><p>You can make sure <code>git show-branch</code> matches the state before
2413 <pre><code>$ git merge commit-fix diff-fix
2414 $ git show-branch
2415 ! [commit-fix] Fix commit message normalization.
2416 ! [diff-fix] Fix rename detection.
2417 * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
2418 ---
2419 - [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
2420 + * [commit-fix] Fix commit message normalization.
2421 +* [diff-fix] Fix rename detection.
2422 +* [diff-fix~1] Better common substring algorithm.
2425 </div></div>
2427 is a valid thing to do and often makes it easier to view the
2428 commit history if you are merging more than two independent
2429 changes at the same time. However, if you have merge conflicts
2430 with any of the branches you are merging in and need to hand
2431 resolve, that is an indication that the development happened in
2432 those branches were not independent after all, and you should
2433 merge two at a time, documenting how you resolved the conflicts,
2434 and the reason why you preferred changes made in one side over
2435 the other. Otherwise it would make the project history harder
2436 to follow, not easier.</p></div>
2437 </div>
2438 </div>
2448 </div>
2449 </div>
2454 </div>
2455 </div>
2456 </div>
2460 Last updated
2462 </div>
2463 </div>
2464 </body>
2465 </html>