| blob | ec665cad56c184232596d78a2e1a16b2ab1866e9 |
4 <head>
9 /* Debug borders */
11 /*
12 border: 1px solid red;
13 */
14 }
16 body {
18 }
20 a {
23 }
26 }
28 em {
31 }
33 strong {
36 }
38 tt {
40 }
48 }
52 }
53 h2 {
55 }
56 h3 {
58 }
59 h3 + * {
61 }
66 }
68 hr {
70 }
72 p {
75 }
79 }
81 pre {
84 }
86 span#author {
91 }
92 span#email {
93 }
96 }
98 div#footer {
104 }
105 div#footer-text {
108 }
109 div#footer-badges {
112 }
114 div#preamble {
117 }
123 }
129 }
133 }
135 /* Block element titles. */
143 }
146 }
150 }
153 }
156 }
162 }
168 }
176 }
181 }
185 }
189 }
190 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
193 }
202 }
206 }
211 }
217 dl {
220 }
221 dt {
226 }
229 }
233 }
236 }
239 }
242 }
245 }
248 }
255 }
259 }
263 }
264 tfoot {
266 }
269 }
272 }
273 /* Because the table frame attribute is overriden by CSS in most browsers. */
276 }
280 }
284 }
290 }
293 }
296 }
302 }
305 }
309 }
313 }
317 }
321 }
326 }
330 }
340 }
345 }
347 div#toc {
349 }
351 div#toctitle {
358 }
363 }
367 }
371 }
375 }
376 /* Overrides for manpage documents */
377 h1 {
382 }
383 h2 {
385 }
388 }
392 }
394 /* Workarounds for IE6's broken and incomplete CSS2. */
400 }
407 }
413 }
418 }
422 }
426 }
431 }
433 /* IE6 sets dynamically generated links as visited. */
435 </style>
437 /*<![CDATA[*/
441 /////////////////////////////////////////////////////////////////////
442 // Table Of Contents generator
443 /////////////////////////////////////////////////////////////////////
445 /* Author: Mihai Bazon, September 2002
446 * http://students.infoiasi.ro/~mishoo
447 *
448 * Table Of Content generator
449 * Version: 0.4
450 *
451 * Feel free to use this script under the terms of the GNU General Public
452 * License, as long as you do not remove or alter this notice.
453 */
455 /* modified by Troy D. Hanson, September 2006. License: GPL */
456 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
458 // toclevels = 1..4.
468 }
470 }
476 }
481 // Function that scans the DOM tree for header elements (the DOM2
482 // nodeIterator API would be a better technique but not supported by all
483 // browsers).
490 }
492 }
493 }
494 }
497 }
512 }
515 },
518 /////////////////////////////////////////////////////////////////////
519 // Footnotes generator
520 /////////////////////////////////////////////////////////////////////
522 /* Based on footnote generation code from:
523 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
524 */
534 n++;
535 // Use [\s\S] in place of . so multi-line matches work.
536 // Because JavaScript has no s (dotall) regex flag.
547 }
548 }
552 // Process footnoterefs.
561 }
562 }
563 }
564 }
566 }
567 /*]]>*/
568 </script>
569 </head>
570 <body>
572 <h1>
573 gitcore-tutorial(7) Manual Page
574 </h1>
577 <p>gitcore-tutorial -
578 A git core tutorial for developers
579 </p>
580 </div>
581 </div>
586 </div>
589 <div class="paragraph"><p>This tutorial explains how to use the "core" git commands to set up and
590 work with a git repository.</p></div>
591 <div class="paragraph"><p>If you just need to use git as a revision control system you may prefer
592 to start with "A Tutorial Introduction to GIT" (<a href="gittutorial.html">gittutorial(7)</a>) or
597 interfaces on top of it called "porcelain". You may not want to use the
598 plumbing directly very often, but it can be good to know what the
601 commands were shell scripts. For simplicity, it still uses them as
602 examples to illustrate how plumbing is fit together to form the
603 porcelain commands. The source tree includes some of these scripts in
604 contrib/examples/ for reference. Although these are not implemented as
605 shell scripts anymore, the description of what the plumbing layer
606 commands do is still valid.</p></div>
608 <table><tr>
611 </td>
613 skip on your first reading.</td>
614 </tr></table>
615 </div>
616 </div>
619 <div class="paragraph"><p>Creating a new git repository couldn’t be easier: all git repositories start
620 out empty, and the only thing you need to do is find yourself a
621 subdirectory that you want to use as a working tree - either an empty
622 one for a totally new project, or an existing working tree that you want
623 to import into git.</p></div>
624 <div class="paragraph"><p>For our first example, we’re going to start a totally new repository from
626 To start up, create a subdirectory for it, change into that
630 <pre><tt>$ mkdir git-tutorial
631 $ cd git-tutorial
632 $ git init</tt></pre>
633 </div></div>
638 </div></div>
639 <div class="paragraph"><p>which is just git’s way of saying that you haven’t been doing anything
643 three entries, among other things:</p></div>
645 <li>
646 <p>
648 This is similar to a symbolic link and points at
650 </p>
651 <div class="paragraph"><p>Don’t worry about the fact that the file that the <tt>HEAD</tt> link points to
654 </li>
655 <li>
656 <p>
658 objects of your project. You should never have any real reason to
659 look at the objects directly, but you might want to know that these
661 </p>
662 </li>
663 <li>
664 <p>
666 </p>
667 </li>
668 </ul></div>
671 exactly what their names imply: they contain references to any number
674 repository.</p></div>
675 <div class="paragraph"><p>One note: the special <tt>master</tt> head is the default branch, which is
678 point to the branch you are working on right now, and you always
683 valid, though.</p></div>
685 <table><tr>
688 </td>
689 <td class="content">An <em>object</em> is identified by its 160-bit SHA1 hash, aka <em>object name</em>,
690 and a reference to an object is always the 40-byte hex
692 subdirectory are expected to contain these hex references
694 expect to see a number of 41-byte files containing these
696 populating your tree.</td>
697 </tr></table>
698 </div>
700 <table><tr>
703 </td>
704 <td class="content">An advanced user may want to take a look at <a href="gitrepository-layout.html">gitrepository-layout(5)</a>
705 after finishing this tutorial.</td>
706 </tr></table>
707 </div>
708 <div class="paragraph"><p>You have now created your first git repository. Of course, since it’s
710 </div>
713 <div class="paragraph"><p>We’ll keep this simple and stupid, so we’ll start off with populating a
714 few trivial files just to get a feel for it.</p></div>
715 <div class="paragraph"><p>Start off with just creating any random files that you want to maintain
716 in your git repository. We’ll start off with a few bad examples, just to
717 get a feel for how this works:</p></div>
722 </div></div>
723 <div class="paragraph"><p>you have now created two files in your working tree (aka <em>working directory</em>),
724 but to actually check in your hard work, you will have to go through two steps:</p></div>
726 <li>
727 <p>
729 working tree state.
730 </p>
731 </li>
732 <li>
733 <p>
734 commit that index file as an object.
735 </p>
736 </li>
737 </ul></div>
738 <div class="paragraph"><p>The first step is trivial: when you want to tell git about any changes
740 program normally just takes a list of filenames you want to update, but
741 to avoid trivial mistakes, it refuses to add new entries to the index
742 (or remove existing ones) unless you explicitly tell it that you’re
745 <div class="paragraph"><p>So to populate the index with the two files you just created, you can do</p></div>
749 </div></div>
752 you’ll notice that git will have added two new objects to the object
753 database. If you did exactly the steps above, you should now be able to do</p></div>
757 </div></div>
763 </div></div>
764 <div class="paragraph"><p>which correspond with the objects with names of <tt>557db…</tt> and
766 <div class="paragraph"><p>If you want to, you can use <em>git cat-file</em> to look at those objects, but
771 </div></div>
772 <div class="paragraph"><p>where the <tt>-t</tt> tells <em>git cat-file</em> to tell you what the "type" of the
773 object is. git will tell you that you have a "blob" object (i.e., just a
774 regular file), and you can see the contents with</p></div>
778 </div></div>
779 <div class="paragraph"><p>which will print out "Hello World". The object <tt>557db03</tt> is nothing
782 <table><tr>
785 </td>
789 we just looked at will never change. Objects are immutable.</td>
790 </tr></table>
791 </div>
793 <table><tr>
796 </td>
798 abbreviate the object name to only the first several
799 hexadecimal digits in most places.</td>
800 </tr></table>
801 </div>
802 <div class="paragraph"><p>Anyway, as we mentioned previously, you normally never actually take a
803 look at the objects themselves, and typing long 40-character hex
804 names is not something you’d normally want to do. The above digression
806 actually saved away the contents of your files into the git object
807 database.</p></div>
808 <div class="paragraph"><p>Updating the index did something else too: it created a <tt>.git/index</tt>
809 file. This is the index that describes your current working tree, and
810 something you should be very aware of. Again, you normally never worry
811 about the index file itself, but you should be aware of the fact that
812 you have not actually really "checked in" your files into git so far,
814 <div class="paragraph"><p>However, since git knows about them, you can now start using some of the
815 most basic git commands to manipulate the files or look at their status.</p></div>
816 <div class="paragraph"><p>In particular, let’s not even check in the two files into git yet, we’ll
821 </div></div>
822 <div class="paragraph"><p>and you can now, since you told git about the previous state of <tt>hello</tt>, ask
823 git what has changed in the tree compared to your old index, using the
828 </div></div>
829 <div class="paragraph"><p>Oops. That wasn’t very readable. It just spit out its own internal
831 that it has noticed that "hello" has been modified, and that the old object
832 contents it had have been replaced with something else.</p></div>
833 <div class="paragraph"><p>To make it readable, we can tell <em>git diff-files</em> to output the
837 <pre><tt>$ git diff-files -p
838 diff --git a/hello b/hello
840 --- a/hello
841 +++ b/hello
843 Hello World
844 +It's a new day for git</tt></pre>
845 </div></div>
846 <div class="paragraph"><p>i.e. the diff of the change we caused by adding another line to <tt>hello</tt>.</p></div>
847 <div class="paragraph"><p>In other words, <em>git diff-files</em> always shows us the difference between
848 what is recorded in the index, and what is currently in the working
850 <div class="paragraph"><p>A common shorthand for <tt>git diff-files -p</tt> is to just write <tt>git
854 <pre><tt>$ git diff
855 diff --git a/hello b/hello
857 --- a/hello
858 +++ b/hello
860 Hello World
861 +It's a new day for git</tt></pre>
862 </div></div>
863 </div>
866 <div class="paragraph"><p>Now, we want to go to the next stage in git, which is to take the files
867 that git knows about in the index, and commit them as a real tree. We do
870 tree was all about, along with information of how we came to that state.</p></div>
871 <div class="paragraph"><p>Creating a tree object is trivial, and is done with <em>git write-tree</em>.
873 current index state, and write an object that describes that whole
874 index. In other words, we’re now tying together all the different
875 filenames with their contents (and their permissions), and we’re
880 </div></div>
881 <div class="paragraph"><p>and this will just output the name of the resulting tree, in this case
886 </div></div>
892 <div class="paragraph"><p>However — normally you’d never use <em>git write-tree</em> on its own, because
893 normally you always commit a tree into a commit object using the
897 <div class="paragraph"><p><em>git commit-tree</em> normally takes several arguments — it wants to know
899 ever in this new repository, and it has no parents, we only need to pass in
901 commit message on its standard input, and it will write out the resulting
902 object name for the commit to its standard output.</p></div>
905 the reference to the top-of-tree of the master branch, and since
907 all with a sequence of simple shell commands:</p></div>
910 <pre><tt>$ tree=$(git write-tree)
911 $ commit=$(echo 'Initial commit' | git commit-tree $tree)
912 $ git update-ref HEAD $commit</tt></pre>
913 </div></div>
916 all later commits will be parented on top of an earlier commit.</p></div>
917 <div class="paragraph"><p>Again, normally you’d never actually do this by hand. There is a
920 instead, and it would have done the above magic scripting for you.</p></div>
921 </div>
924 <div class="paragraph"><p>Remember how we did the <em>git update-index</em> on file <tt>hello</tt> and then we
926 state we saved in the index file?</p></div>
927 <div class="paragraph"><p>Further, remember how I said that <em>git write-tree</em> writes the contents
929 fact the <strong>original</strong> contents of the file <tt>hello</tt>, not the new ones. We did
930 that on purpose, to show the difference between the index state, and the
931 state in the working tree, and how they don’t have to match, even
932 when we commit things.</p></div>
933 <div class="paragraph"><p>As before, if we do <tt>git diff-files -p</tt> in our git-tutorial project,
934 we’ll still see the same difference we saw last time: the index file
935 hasn’t changed by the act of committing anything. However, now that we
936 have committed something, we can also learn to use a new command:
938 <div class="paragraph"><p>Unlike <em>git diff-files</em>, which showed the difference between the index
942 against, and before we did the commit, we couldn’t do that, because we
948 </div></div>
949 <div class="paragraph"><p>(where <tt>-p</tt> has the same meaning as it did in <em>git diff-files</em>), and it
950 will show us the same difference, but for a totally different reason.
951 Now we’re comparing the working tree not against the index file,
952 but against the tree we just wrote. It just so happens that those two
953 are obviously the same, so we get the same result.</p></div>
954 <div class="paragraph"><p>Again, because this is a common operation, you can also just shorthand
955 it with</p></div>
959 </div></div>
961 <div class="paragraph"><p>In other words, <em>git diff-index</em> normally compares a tree against the
963 instead compare against just the index cache contents, and ignore the
964 current working tree state entirely. Since we just wrote the index
968 <table><tr>
971 </td>
974 comparisons, and saying that it compares a tree against the working
975 tree is thus not strictly accurate. In particular, the list of
979 come from the working tree or not.</p></div>
980 <div class="paragraph"><p>This is not hard to understand, as soon as you realize that git simply
981 never knows (or cares) about files that it is not told about
983 expects you to tell it what the files are, and that’s what the index
984 is there for.</p></div>
985 </td>
986 </tr></table>
987 </div>
988 <div class="paragraph"><p>However, our next step is to commit the <strong>change</strong> we did, and again, to
991 in the working tree that we want to commit, and we always have to
992 work through the index file, so the first thing we need to do is to
993 update the index cache:</p></div>
997 </div></div>
998 <div class="paragraph"><p>(note how we didn’t need the <tt>--add</tt> flag this time, since git knew
999 about the file already).</p></div>
1000 <div class="paragraph"><p>Note what happens to the different <em>git diff-*</em> versions here.
1003 current state is different from the state we committed. In fact, now
1005 flag or not, since now the index is coherent with the working tree.</p></div>
1006 <div class="paragraph"><p>Now, since we’ve updated <tt>hello</tt> in the index, we can commit the new
1007 version. We could do it by writing the tree by hand again, and
1015 </div></div>
1016 <div class="paragraph"><p>which starts an editor for you to write the commit message and tells you
1017 a bit about what you have done.</p></div>
1018 <div class="paragraph"><p>Write whatever message you want, and all the lines that start with <em>#</em>
1019 will be pruned out, and the rest will be used as the commit message for
1020 the change. If you decide you don’t want to commit anything after all at
1021 this point (you can continue to edit things and update the index), you
1023 the change for you.</p></div>
1024 <div class="paragraph"><p>You’ve now made your first real git commit. And if you’re interested in
1026 it’s a few very simple shell scripts to generate the helpful (?) commit
1027 message headers, and a few one-liners that actually do the
1029 </div>
1032 <div class="paragraph"><p>While creating changes is useful, it’s even more useful if you can tell
1033 later what changed. The most useful command for this is another of the
1035 <div class="paragraph"><p><em>git diff-tree</em> can be given two arbitrary trees, and it will tell you the
1036 differences between them. Perhaps even more commonly, though, you can
1037 give it just a single commit object, and it will figure out the parent
1038 of that commit itself, and show the difference directly. Thus, to get
1043 </div></div>
1044 <div class="paragraph"><p>(again, <tt>-p</tt> means to show the difference as a human-readable patch),
1047 <table><tr>
1050 </td>
1056 <pre><tt> diff-tree
1057 +----+
1058 | |
1059 | |
1060 V V
1061 +-----------+
1062 | Object DB |
1063 | Backing |
1064 | Store |
1065 +-----------+
1066 ^ ^
1067 | |
1068 | | diff-index --cached
1069 | |
1070 diff-index | V
1071 | +-----------+
1072 | | Index |
1073 | | "cache" |
1074 | +-----------+
1075 | ^
1076 | |
1077 | | diff-files
1078 | |
1079 V V
1080 +-----------+
1081 | Working |
1082 | Directory |
1083 +-----------+</tt></pre>
1084 </div></div>
1085 </td>
1086 </tr></table>
1087 </div>
1088 <div class="paragraph"><p>More interestingly, you can also give <em>git diff-tree</em> the <tt>--pretty</tt> flag,
1089 which tells it to also show the commit message and author and date of the
1090 commit, and you can tell it to show a whole series of diffs.
1091 Alternatively, you can tell it to be "silent", and not show the diffs at
1092 all, but just show the actual commit message.</p></div>
1093 <div class="paragraph"><p>In fact, together with the <em>git rev-list</em> program (which generates a
1096 included with git which does exactly this, and shows a log of recent
1097 activities.</p></div>
1098 <div class="paragraph"><p>To see the whole history of our pitiful little git-tutorial project, you
1099 can do</p></div>
1103 </div></div>
1104 <div class="paragraph"><p>which shows just the log messages, or if we want to see the log together
1105 with the associated patches use the more complex (and much more
1106 powerful)</p></div>
1110 </div></div>
1112 short history.</p></div>
1114 <table><tr>
1117 </td>
1119 If this is a problem because it is huge, you can hide it by setting
1120 the log.showroot configuration variable to false. Having this, you
1123 </tr></table>
1124 </div>
1125 <div class="paragraph"><p>With that, you should now be having some inkling of what git does, and
1126 can explore on your own.</p></div>
1128 <table><tr>
1131 </td>
1135 </tr></table>
1136 </div>
1137 </div>
1140 <div class="paragraph"><p>In git, there are two kinds of tags, a "light" one, and an "annotated tag".</p></div>
1141 <div class="paragraph"><p>A "light" tag is technically nothing more than a branch, except we put
1143 So the simplest form of tag involves nothing more than</p></div>
1147 </div></div>
1148 <div class="paragraph"><p>which just writes the current <tt>HEAD</tt> into the <tt>.git/refs/tags/my-first-tag</tt>
1149 file, after which point you can then use this symbolic name for that
1150 particular state. You can, for example, do</p></div>
1154 </div></div>
1156 obviously be an empty diff, but if you continue to develop and commit
1157 stuff, you can use your tag as an "anchor-point" to see what has changed
1158 since you tagged it.</p></div>
1159 <div class="paragraph"><p>An "annotated tag" is actually a real git object, and contains not only a
1160 pointer to the state you want to tag, but also a small tag name and
1161 message, along with optionally a PGP signature that says that yes,
1162 you really did
1168 </div></div>
1169 <div class="paragraph"><p>which will sign the current <tt>HEAD</tt> (but you can also give it another
1170 argument that specifies the thing to tag, e.g., you could have tagged the
1173 like that, while the light-weight tags are useful for any marking you
1174 want to do — any time you decide that you want to remember a certain
1175 point, just create a private tag for it, and you have a nice symbolic
1176 name for the state at that point.</p></div>
1177 </div>
1180 <div class="paragraph"><p>git repositories are normally totally self-sufficient and relocatable.
1181 Unlike CVS, for example, there is no separate notion of
1184 subdirectory. There is nothing else. What you see is what you got.</p></div>
1186 <table><tr>
1189 </td>
1192 how normal projects work, and it’s really only meant for special uses.
1193 So the mental model of "the git information is always tied directly to
1196 </tr></table>
1197 </div>
1200 <li>
1201 <p>
1202 if you grow bored with the tutorial repository you created (or you’ve
1203 made a mistake and want to start all over), you can just do simple
1204 </p>
1208 </div></div>
1209 <div class="paragraph"><p>and it will be gone. There’s no external repository, and there’s no
1210 history outside the project you created.</p></div>
1211 </li>
1212 <li>
1213 <p>
1214 if you want to move or duplicate a git repository, you can do so. There
1216 create a copy of your repository (with all the full history that
1217 went along with it), you can do so with a regular
1219 </p>
1220 <div class="paragraph"><p>Note that when you’ve moved or copied a git repository, your git index
1221 file (which caches various information, notably some of the "stat"
1222 information for the files involved) will likely need to be refreshed.
1227 </div></div>
1228 <div class="paragraph"><p>in the new repository to make sure that the index file is up-to-date.</p></div>
1229 </li>
1230 </ul></div>
1234 <div class="paragraph"><p>When copying a remote repository, you’ll want to at a minimum update the
1235 index cache when you do this, and especially with other peoples'
1236 repositories you often want to make sure that the index cache is in some
1237 known state (you don’t know <strong>what</strong> they’ve done and not yet checked in),
1241 <pre><tt>$ git read-tree --reset HEAD
1242 $ git update-index --refresh</tt></pre>
1243 </div></div>
1244 <div class="paragraph"><p>which will force a total index re-build from the tree pointed to by <tt>HEAD</tt>.
1246 makes sure to match up all index entries with the checked-out files.
1247 If the original repository had uncommitted changes in its
1249 tells you they need to be updated.</p></div>
1254 </div></div>
1255 <div class="paragraph"><p>and in fact a lot of the common git command combinations can be scripted
1260 the basic git commands.</p></div>
1263 actual core git files. Such a repository usually doesn’t even have the
1265 repository.</p></div>
1266 <div class="paragraph"><p>To create your own local live copy of such a "raw" git repository, you’d
1267 first create your own subdirectory for the project, and then copy the
1272 <pre><tt>$ mkdir my-git
1273 $ cd my-git
1274 $ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git</tt></pre>
1275 </div></div>
1280 </div></div>
1281 <div class="paragraph"><p>to populate the index. However, now you have populated the index, and
1282 you have all the git internal files, but you will notice that you don’t
1283 actually have any of the working tree files to work on. To get
1288 </div></div>
1289 <div class="paragraph"><p>where the <tt>-u</tt> flag means that you want the checkout to keep the index
1290 up-to-date (so that you don’t have to refresh it afterward), and the
1293 flag first, to tell <em>git checkout-index</em> to <strong>force</strong> overwriting of any old
1294 files).</p></div>
1298 <pre><tt>$ git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git
1299 $ cd my-git
1300 $ git checkout</tt></pre>
1301 </div></div>
1304 repository, and checked it out.</p></div>
1305 </div>
1311 these object pointers.</p></div>
1313 point in the project history, and just writing the SHA1 name of that
1315 want (and indeed, subdirectories), but the convention is that the
1317 and nothing enforces it.</p></div>
1318 <div class="paragraph"><p>To show that as an example, let’s go back to the git-tutorial repository we
1319 used earlier, and create a branch in it. You do that by simply just
1320 saying that you want to check out a new branch:</p></div>
1324 </div></div>
1325 <div class="paragraph"><p>will create a new branch based at the current <tt>HEAD</tt> position, and switch
1326 to it.</p></div>
1328 <table><tr>
1331 </td>
1340 </div></div>
1341 <div class="paragraph"><p>and it would create the new branch <tt>mybranch</tt> at the earlier commit,
1342 and check out the state at that time.</p></div>
1343 </td>
1344 </tr></table>
1345 </div>
1346 <div class="paragraph"><p>You can always just jump back to your original <tt>master</tt> branch by doing</p></div>
1350 </div></div>
1352 branch you happen to be on, a simple</p></div>
1356 </div></div>
1358 you have, you can say</p></div>
1362 </div></div>
1363 <div class="paragraph"><p>which used to be nothing more than a simple script around <tt>ls .git/refs/heads</tt>.
1364 There will be an asterisk in front of the branch you are currently on.</p></div>
1365 <div class="paragraph"><p>Sometimes you may wish to create a new branch <em>without</em> actually
1366 checking it out and switching to it. If so, just use the command</p></div>
1370 </div></div>
1371 <div class="paragraph"><p>which will simply <em>create</em> the branch, but will not do anything further.
1372 You can then later — once you decide that you want to actually develop
1374 with the branchname as the argument.</p></div>
1375 </div>
1379 experimental) work in it, and eventually merge it back to the main
1382 that branch, and do some work there.</p></div>
1385 <pre><tt>$ git checkout mybranch
1388 </div></div>
1389 <div class="paragraph"><p>Here, we just added another line to <tt>hello</tt>, and we used a shorthand for
1394 commit log message from the command line.</p></div>
1395 <div class="paragraph"><p>Now, to make it a bit more interesting, let’s assume that somebody else
1396 does some work in the original branch, and simulate that by going back
1397 to the master branch, and editing the same file differently there:</p></div>
1401 </div></div>
1402 <div class="paragraph"><p>Here, take a moment to look at the contents of <tt>hello</tt>, and notice how they
1403 don’t contain the work we just did in <tt>mybranch</tt> — because that work
1410 </div></div>
1411 <div class="paragraph"><p>since the master branch is obviously in a much better mood.</p></div>
1412 <div class="paragraph"><p>Now, you’ve got two branches, and you decide that you want to merge the
1413 work done. Before we do that, let’s introduce a cool graphical tool that
1418 </div></div>
1419 <div class="paragraph"><p>will show you graphically both of your branches (that’s what the <tt>--all</tt>
1421 histories. You can also see exactly how they came to be from a common
1422 source.</p></div>
1423 <div class="paragraph"><p>Anyway, let’s exit <em>gitk</em> (<tt>^Q</tt> or the File menu), and decide that we want
1427 to resolve and what the merge is all about:</p></div>
1431 </div></div>
1432 <div class="paragraph"><p>where the first argument is going to be used as the commit message if
1433 the merge can be resolved automatically.</p></div>
1434 <div class="paragraph"><p>Now, in this case we’ve intentionally created a situation where the
1435 merge will need to be fixed up by hand, though, so git will do as much
1440 <pre><tt> Auto-merging hello
1441 CONFLICT (content): Merge conflict in hello
1442 Automatic merge failed; fix conflicts and then commit the result.</tt></pre>
1443 </div></div>
1446 <div class="paragraph"><p>Not to worry. It left the (trivial) conflict in <tt>hello</tt> in the same form you
1452 <pre><tt>Hello World
1453 It's a new day for git
1454 Play, play, play
1455 Work, work, work</tt></pre>
1456 </div></div>
1457 <div class="paragraph"><p>and once you’re happy with your manual merge, just do a</p></div>
1461 </div></div>
1462 <div class="paragraph"><p>which will very loudly warn you that you’re now committing a merge
1463 (which is correct, so never mind), and you can write a small merge
1465 <div class="paragraph"><p>After you’re done, start up <tt>gitk --all</tt> to see graphically what the
1467 switch to it, and continue to work with it if you want to. The
1471 <div class="paragraph"><p>Another useful tool, especially if you do not always work in X-Window
1476 * [master] Merge work in mybranch
1477 ! [mybranch] Some work.
1478 --
1479 - [master] Merge work in mybranch
1480 *+ [mybranch] Some work.
1481 * [master^] Some fun.</tt></pre>
1482 </div></div>
1484 and the first line of the commit log message from their
1487 the later output lines is used to show commits contained in the
1489 branch. Three commits are shown along with their log messages.
1495 commits from the master branch. The string inside brackets
1496 before the commit log message is a short name you can use to
1500 see more complex cases.</p></div>
1502 <table><tr>
1505 </td>
1506 <td class="content">Without the <em>--more=1</em> option, <em>git show-branch</em> would not output the
1508 both <em>master</em> and <em>mybranch</em> tips. Please see <a href="git-show-branch.html">git-show-branch(1)</a>
1509 for details.</td>
1510 </tr></table>
1511 </div>
1513 <table><tr>
1516 </td>
1517 <td class="content">If there were more commits on the <em>master</em> branch after the merge, the
1520 merge commit visible in this case.</td>
1521 </tr></table>
1522 </div>
1529 <pre><tt>$ git checkout mybranch
1531 </div></div>
1533 would be different)</p></div>
1536 <pre><tt>Updating from ae3a2da... to a80b4aa....
1537 Fast-forward (no commit created; -m option ignored)
1538 example | 1 +
1539 hello | 1 +
1541 </div></div>
1544 not actually do a merge. Instead, it just updated the top of
1551 <pre><tt>$ git show-branch master mybranch
1552 ! [master] Merge work in mybranch
1553 * [mybranch] Merge work in mybranch
1554 --
1555 -- [master] Merge work in mybranch</tt></pre>
1556 </div></div>
1557 </div>
1560 <div class="paragraph"><p>It’s usually much more common that you merge with somebody else than
1561 merging with your own branches, so it’s worth pointing out that git
1562 makes that very easy too, and in fact, it’s not that different from
1564 more than "fetch the work from a remote repository into a temporary tag"
1571 </div></div>
1573 repository to download from:</p></div>
1576 Rsync
1577 </dt>
1578 <dd>
1579 <p>
1581 </p>
1583 but is completely unaware of what git does, and can produce
1584 unexpected results when you download from the public repository
1586 transport. Most notably, it could update the files under
1589 obtain head commit object name while that object itself is still
1590 not available in the repository. For this reason, it is
1591 considered deprecated.</p></div>
1592 </dd>
1594 SSH
1595 </dt>
1596 <dd>
1597 <p>
1599 </p>
1603 remote machine. It finds out the set of objects the other side
1604 lacks by exchanging the head commits both ends have and
1605 transfers (close to) minimum set of objects. It is by far the
1606 most efficient way to exchange git objects between repositories.</p></div>
1607 </dd>
1609 Local directory
1610 </dt>
1611 <dd>
1612 <p>
1614 </p>
1615 <div class="paragraph"><p>This transport is the same as SSH transport but uses <em>sh</em> to run
1616 both ends on the local machine instead of running other end on
1618 </dd>
1620 git Native
1621 </dt>
1622 <dd>
1623 <p>
1625 </p>
1627 transport, it finds out the set of objects the downstream side
1628 lacks and transfers (close to) minimum set of objects.</p></div>
1629 </dd>
1631 HTTP(S)
1632 </dt>
1633 <dd>
1634 <p>
1636 </p>
1638 first obtains the topmost commit object name from the remote site
1640 and then tries to obtain the
1642 using the object name of that commit object. Then it reads the
1643 commit object to find out its parent commits and the associate
1644 tree object; it repeats this process until it gets all the
1645 necessary objects. Because of this behavior, they are
1648 transports</em>, because they do not require any git aware smart
1649 server like git Native transport does. Any stock HTTP server
1650 that does not even support directory index would suffice. But
1652 to help dumb transport downloaders.</p></div>
1653 </dd>
1654 </dl></div>
1656 with your current branch.</p></div>
1657 <div class="paragraph"><p>However — it’s such a common thing to <tt>fetch</tt> and then
1659 simply do</p></div>
1663 </div></div>
1665 argument.</p></div>
1667 <table><tr>
1670 </td>
1672 keeping as many local repositories as you would like to have
1674 you merge between branches. The advantage of this approach is
1676 out and you may find it easier to switch back and forth if you
1677 juggle multiple lines of development simultaneously. Of
1678 course, you will pay the price of more disk usage to hold
1679 multiple working trees, but disk space is cheap these days.</td>
1680 </tr></table>
1681 </div>
1683 repository from time to time. As a short hand, you can store
1684 the remote repository URL in the local repository’s config file
1685 like this:</p></div>
1689 </div></div>
1690 <div class="paragraph"><p>and use the "linus" keyword with <em>git pull</em> instead of the full URL.</p></div>
1693 <li>
1694 <p>
1696 </p>
1697 </li>
1698 <li>
1699 <p>
1701 </p>
1702 </li>
1703 </ol></div>
1706 <li>
1707 <p>
1708 <tt>git pull <a href="http://www.kernel.org/pub/scm/git/git.git/">http://www.kernel.org/pub/scm/git/git.git/</a> HEAD</tt>
1709 </p>
1710 </li>
1711 <li>
1712 <p>
1713 <tt>git pull <a href="http://www.kernel.org/pub/scm/git/git.git/">http://www.kernel.org/pub/scm/git/git.git/</a> tag v0.99.1</tt>
1714 </p>
1715 </li>
1716 </ol></div>
1717 </div>
1721 with the porcelain that isn’t flushing, but we so far did not
1722 talk about how the merge really works. If you are following
1727 and bring ourselves back to the pre-merge state:</p></div>
1731 ! [master] Merge work in mybranch
1732 * [mybranch] Merge work in mybranch
1733 --
1734 -- [master] Merge work in mybranch
1735 +* [master^2] Some work.
1736 +* [master^] Some fun.</tt></pre>
1737 </div></div>
1738 <div class="paragraph"><p>Remember, before running <em>git merge</em>, our <tt>master</tt> head was at
1743 <pre><tt>$ git checkout mybranch
1744 $ git reset --hard master^2
1745 $ git checkout master
1746 $ git reset --hard master^</tt></pre>
1747 </div></div>
1748 <div class="paragraph"><p>After rewinding, the commit structure should look like this:</p></div>
1751 <pre><tt>$ git show-branch
1752 * [master] Some fun.
1753 ! [mybranch] Some work.
1754 --
1755 * [master] Some fun.
1756 + [mybranch] Some work.
1757 *+ [master^] Initial commit</tt></pre>
1758 </div></div>
1760 <div class="paragraph"><p><tt>git merge</tt> command, when merging two branches, uses 3-way merge
1761 algorithm. First, it finds the common ancestor between them.
1766 </div></div>
1768 to the standard output, so we captured its output to a variable,
1769 because we will be using it in the next step. By the way, the common
1770 ancestor commit is the "Initial commit" commit in this case. You can
1771 tell it by:</p></div>
1774 <pre><tt>$ git name-rev --name-only --tags $mb
1775 my-first-tag</tt></pre>
1776 </div></div>
1778 this:</p></div>
1782 </div></div>
1783 <div class="paragraph"><p>This is the same <em>git read-tree</em> command we have already seen,
1784 but it takes three trees, unlike previous examples. This reads
1787 etc.). After reading three trees into three stages, the paths
1789 0. Also paths that are the same in two of three stages are
1792 changed from the common ancestor).</p></div>
1793 <div class="paragraph"><p>After <em>collapsing</em> operation, paths that are different in three
1794 trees are left in non-zero stages. At this point, you can
1795 inspect the index file with this command:</p></div>
1798 <pre><tt>$ git ls-files --stage
1803 </div></div>
1806 large projects, when only a small number of files change in one commit,
1808 fairly quickly, leaving only a handful of real changes in non-zero
1809 stages.</p></div>
1810 <div class="paragraph"><p>To look at only non-zero stages, use <tt>--unmerged</tt> flag:</p></div>
1813 <pre><tt>$ git ls-files --unmerged
1817 </div></div>
1819 file, using 3-way merge. This is done by giving
1824 <pre><tt>$ git merge-index git-merge-one-file hello
1825 Auto-merging hello
1826 ERROR: Merge conflict in hello
1827 fatal: merge program failed</tt></pre>
1828 </div></div>
1830 describe those three versions, and is responsible to leave the
1831 merge results in the working tree.
1832 It is a fairly straightforward shell script, and
1835 conflicts, and the merge result with conflict marks is left in
1836 the working tree.. This can be seen if you run <tt>ls-files
1840 <pre><tt>$ git ls-files --stage
1845 </div></div>
1851 </div>
1854 <div class="paragraph"><p>So, we can use somebody else’s work from a remote repository, but
1856 it?</p></div>
1860 people to pull from it, but in practice that is not the way
1861 things are usually done. A recommended way is to have a public
1862 repository, make it reachable by other people, and when the
1863 changes you made in your primary working tree are in good shape,
1864 update the public repository from it. This is often called
1867 <table><tr>
1870 </td>
1873 </tr></table>
1874 </div>
1876 your remote (public) repository requires a write privilege on
1877 the remote machine. You need to have an SSH account there to
1880 machine that will house your public repository. This empty
1881 repository will be populated and be kept up-to-date by pushing
1882 into it later. Obviously, this repository creation needs to be
1883 done only once.</p></div>
1885 <table><tr>
1888 </td>
1891 on the remote machine. The communication between the two over
1892 the network internally uses an SSH connection.</td>
1893 </tr></table>
1894 </div>
1895 <div class="paragraph"><p>Your private repository’s git directory is usually <tt>.git</tt>, but
1896 your public repository is often named after the project name,
1899 an empty directory:</p></div>
1903 </div></div>
1910 </div></div>
1912 changes to be pulled via the transport of your choice. Also
1916 <table><tr>
1919 </td>
1921 shell when you directly run programs; what this means is that if
1925 </tr></table>
1926 </div>
1928 <table><tr>
1931 </td>
1933 you should do <tt>mv my-git.git/hooks/post-update.sample
1934 my-git.git/hooks/post-update</tt> at this point.
1935 This makes sure that every time you push into this
1937 </tr></table>
1938 </div>
1940 Come back to the machine you have your private repository. From
1941 there, run this command:</p></div>
1945 </div></div>
1948 from them in your current repository.</p></div>
1950 repository. Kernel.org mirror network takes care of the
1951 propagation to other publicly visible machines:</p></div>
1955 </div></div>
1956 </div>
1959 <div class="paragraph"><p>Earlier, we saw that one file under <tt>.git/objects/??/</tt> directory
1960 is stored for each git object you create. This representation
1961 is efficient to create atomically and safely, but
1962 not so convenient to transport over the network. Since git objects are
1963 immutable once they are created, there is a way to optimize the
1968 </div></div>
1973 directory.</p></div>
1975 <table><tr>
1978 </td>
1979 <td class="content">You will see two files, <tt>pack-*.pack</tt> and <tt>pack-*.idx</tt>,
1981 each other, and if you ever copy them by hand to a different
1982 repository for whatever reason, you should make sure you copy
1983 them together. The former holds all the data from the objects
1984 in the pack, and the latter holds the index for random
1985 access.</td>
1986 </tr></table>
1987 </div>
1989 detect if you have a corrupt pack, but do not worry too much.
1990 Our programs are always perfect ;-).</p></div>
1992 unpacked objects that are contained in the pack file anymore.</p></div>
1996 </div></div>
1998 <div class="paragraph"><p>You can try running <tt>find .git/objects -type f</tt> before and after
2000 count-objects</tt> would tell you how many unpacked objects are in
2001 your repository and how much space they are consuming.</p></div>
2003 <table><tr>
2006 </td>
2008 packed repository may contain relatively few objects in a
2009 relatively large pack. If you expect many HTTP pulls from your
2010 public repository you might want to repack & prune often, or
2011 never.</td>
2012 </tr></table>
2013 </div>
2015 "Nothing new to pack.". Once you continue your development and
2017 new pack, that contains objects created since you packed your
2018 repository the last time. We recommend that you pack your project
2019 soon after the initial import (unless you are starting your
2021 while, depending on how active your project is.</p></div>
2022 <div class="paragraph"><p>When a repository is synchronized via <tt>git push</tt> and <tt>git pull</tt>
2023 objects packed in the source repository are usually stored
2024 unpacked in the destination, unless rsync transport is used.
2025 While this allows you to use different packing strategies on
2026 both ends, it also means you may need to repack both
2027 repositories every once in a while.</p></div>
2028 </div>
2032 convenient to organize your project with an informal hierarchy
2033 of developers. Linux kernel development is run this way. There
2035 <a href="http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf">Randy Dunlap’s presentation</a>.</p></div>
2036 <div class="paragraph"><p>It should be stressed that this hierarchy is purely <strong>informal</strong>.
2037 There is nothing fundamental in git that enforces the "chain of
2038 patch flow" this hierarchy implies. You do not have to pull
2039 from only one remote repository.</p></div>
2040 <div class="paragraph"><p>A recommended workflow for a "project lead" goes like this:</p></div>
2042 <li>
2043 <p>
2044 Prepare your primary repository on your local machine. Your
2045 work is done there.
2046 </p>
2047 </li>
2048 <li>
2049 <p>
2050 Prepare a public repository accessible to others.
2051 </p>
2053 transport protocols (HTTP), you need to keep this repository
2057 but you need to manually enable the hook with
2060 </li>
2061 <li>
2062 <p>
2063 Push into the public repository from your primary
2064 repository.
2065 </p>
2066 </li>
2067 <li>
2068 <p>
2070 pack that contains the initial set of objects as the
2072 used for pulling from your repository supports packed
2073 repositories.
2074 </p>
2075 </li>
2076 <li>
2077 <p>
2078 Keep working in your primary repository. Your changes
2079 include modifications of your own, patches you receive via
2080 e-mails, and merges resulting from pulling the "public"
2081 repositories of your "subsystem maintainers".
2082 </p>
2083 <div class="paragraph"><p>You can repack this private repository whenever you feel like.</p></div>
2084 </li>
2085 <li>
2086 <p>
2087 Push your changes to the public repository, and announce it
2088 to the public.
2089 </p>
2090 </li>
2091 <li>
2092 <p>
2094 Go back to step 5. and continue working.
2095 </p>
2096 </li>
2097 </ol></div>
2101 <li>
2102 <p>
2104 repository of the "project lead". The URL used for the
2105 initial cloning is stored in the remote.origin.url
2106 configuration variable.
2107 </p>
2108 </li>
2109 <li>
2110 <p>
2111 Prepare a public repository accessible to others, just like
2112 the "project lead" person does.
2113 </p>
2114 </li>
2115 <li>
2116 <p>
2117 Copy over the packed files from "project lead" public
2118 repository to your public repository, unless the "project
2119 lead" repository lives on the same machine as yours. In the
2121 point at the repository you are borrowing from.
2122 </p>
2123 </li>
2124 <li>
2125 <p>
2126 Push into the public repository from your primary
2128 transport used for pulling from your repository supports
2129 packed repositories.
2130 </p>
2131 </li>
2132 <li>
2133 <p>
2134 Keep working in your primary repository. Your changes
2135 include modifications of your own, patches you receive via
2136 e-mails, and merges resulting from pulling the "public"
2137 repositories of your "project lead" and possibly your
2138 "sub-subsystem maintainers".
2139 </p>
2141 like.</p></div>
2142 </li>
2143 <li>
2144 <p>
2145 Push your changes to your public repository, and ask your
2147 maintainers" to pull from it.
2148 </p>
2149 </li>
2150 <li>
2151 <p>
2153 Go back to step 5. and continue working.
2154 </p>
2155 </li>
2156 </ol></div>
2158 not have a "public" repository is somewhat different. It goes
2159 like this:</p></div>
2161 <li>
2162 <p>
2165 maintainer", if you work on a subsystem). The URL used for
2166 the initial cloning is stored in the remote.origin.url
2167 configuration variable.
2168 </p>
2169 </li>
2170 <li>
2171 <p>
2173 </p>
2174 </li>
2175 <li>
2176 <p>
2178 upstream every once in a while. This does only the first
2181 </p>
2182 </li>
2183 <li>
2184 <p>
2187 unmerged changes forward to the updated upstream.
2188 </p>
2189 </li>
2190 <li>
2191 <p>
2193 submission to your upstream and send it out. Go back to
2194 step 2. and continue.
2195 </p>
2196 </li>
2197 </ol></div>
2198 </div>
2199 <h2 id="_working_with_others_shared_repository_style">Working with Others, Shared Repository Style</h2>
2202 suggested in the previous section may be new to you. You do not
2203 have to worry. git supports "shared public repository" style of
2204 cooperation you are probably more familiar with as well.</p></div>
2205 <div class="paragraph"><p>See <a href="gitcvs-migration.html">gitcvs-migration(7)</a> for the details.</p></div>
2206 </div>
2210 a time. It is easy to manage those more-or-less independent tasks
2211 using branches with git.</p></div>
2213 with "fun and work" example using two branches. The idea is the
2214 same if there are more than two branches. Let’s say you started
2216 branch, and two independent fixes in the "commit-fix" and
2220 <pre><tt>$ git show-branch
2221 ! [commit-fix] Fix commit message normalization.
2222 ! [diff-fix] Fix rename detection.
2223 * [master] Release candidate #1
2224 ---
2225 + [diff-fix] Fix rename detection.
2226 + [diff-fix~1] Better common substring algorithm.
2227 + [commit-fix] Fix commit message normalization.
2228 * [master] Release candidate #1
2230 </div></div>
2238 </div></div>
2242 <pre><tt>$ git show-branch
2243 ! [commit-fix] Fix commit message normalization.
2244 ! [diff-fix] Fix rename detection.
2245 * [master] Merge fix in commit-fix
2246 ---
2247 - [master] Merge fix in commit-fix
2248 + * [commit-fix] Fix commit message normalization.
2249 - [master~1] Merge fix in diff-fix
2250 +* [diff-fix] Fix rename detection.
2251 +* [diff-fix~1] Better common substring algorithm.
2254 </div></div>
2256 first and the other next, when what you have are a set of truly
2257 independent changes (if the order mattered, then they are not
2258 independent by definition). You could instead merge those two
2259 branches into the current branch at once. First let’s undo what
2260 we just did and start over. We would want to get the master
2265 </div></div>
2272 <pre><tt>$ git merge commit-fix diff-fix
2273 $ git show-branch
2274 ! [commit-fix] Fix commit message normalization.
2275 ! [diff-fix] Fix rename detection.
2276 * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
2277 ---
2278 - [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
2279 + * [commit-fix] Fix commit message normalization.
2280 +* [diff-fix] Fix rename detection.
2281 +* [diff-fix~1] Better common substring algorithm.
2284 </div></div>
2286 is a valid thing to do and often makes it easier to view the
2287 commit history if you are merging more than two independent
2288 changes at the same time. However, if you have merge conflicts
2289 with any of the branches you are merging in and need to hand
2290 resolve, that is an indication that the development happened in
2291 those branches were not independent after all, and you should
2292 merge two at a time, documenting how you resolved the conflicts,
2293 and the reason why you preferred changes made in one side over
2294 the other. Otherwise it would make the project history harder
2295 to follow, not easier.</p></div>
2296 </div>
2305 </div>
2309 </div>
2310 </div>
2315 </div>
2316 </div>
2317 </body>
2318 </html>