| blob | 119b18f09d3f6085e98e4249d49140aab73b6433 |
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 }
127 }
131 }
133 /* Block element titles. */
141 }
144 }
148 }
151 }
154 }
160 }
166 }
171 }
175 }
180 }
183 }
187 }
188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
191 }
200 }
204 }
209 }
215 dl {
218 }
219 dt {
224 }
227 }
231 }
234 }
237 }
240 }
243 }
246 }
253 }
257 }
258 thead {
261 }
262 tfoot {
264 }
267 }
270 }
271 /* Because the table frame attribute is overriden by CSS in most browsers. */
274 }
278 }
282 }
288 }
291 }
294 }
300 }
303 }
307 }
311 }
315 }
317 div#toctitle {
324 }
329 }
333 }
337 }
341 }
342 /* Overrides for manpage documents */
343 h1 {
348 }
349 h2 {
351 }
354 }
358 }
360 /* Workarounds for IE6's broken and incomplete CSS2. */
366 }
373 }
379 }
384 }
388 }
392 }
397 }
399 /* IE6 sets dynamically generated links as visited. */
401 </style>
402 </head>
403 <body>
405 <h1>
406 gitcore-tutorial(7) Manual Page
407 </h1>
410 <p>gitcore-tutorial -
411 A git core tutorial for developers
412 </p>
413 </div>
414 </div>
418 </div>
421 <div class="paragraph"><p>This tutorial explains how to use the "core" git commands to set up and
422 work with a git repository.</p></div>
423 <div class="paragraph"><p>If you just need to use git as a revision control system you may prefer
424 to start with "A Tutorial Introduction to GIT" (<a href="gittutorial.html">gittutorial(7)</a>) or
429 interfaces on top of it called "porcelain". You may not want to use the
430 plumbing directly very often, but it can be good to know what the
433 commands were shell scripts. For simplicity, it still uses them as
434 examples to illustrate how plumbing is fit together to form the
435 porcelain commands. The source tree includes some of these scripts in
436 contrib/examples/ for reference. Although these are not implemented as
437 shell scripts anymore, the description of what the plumbing layer
438 commands do is still valid.</p></div>
440 <table><tr>
443 </td>
445 skip on your first reading.</td>
446 </tr></table>
447 </div>
448 </div>
451 <div class="paragraph"><p>Creating a new git repository couldn’t be easier: all git repositories start
452 out empty, and the only thing you need to do is find yourself a
453 subdirectory that you want to use as a working tree - either an empty
454 one for a totally new project, or an existing working tree that you want
455 to import into git.</p></div>
456 <div class="paragraph"><p>For our first example, we’re going to start a totally new repository from
458 To start up, create a subdirectory for it, change into that
462 <pre><tt>$ mkdir git-tutorial
463 $ cd git-tutorial
464 $ git init</tt></pre>
465 </div></div>
470 </div></div>
471 <div class="paragraph"><p>which is just git’s way of saying that you haven’t been doing anything
475 three entries, among other things:</p></div>
477 <li>
478 <p>
480 This is similar to a symbolic link and points at
482 </p>
483 <div class="paragraph"><p>Don’t worry about the fact that the file that the <tt>HEAD</tt> link points to
486 </li>
487 <li>
488 <p>
490 objects of your project. You should never have any real reason to
491 look at the objects directly, but you might want to know that these
493 </p>
494 </li>
495 <li>
496 <p>
498 </p>
499 </li>
500 </ul></div>
503 exactly what their names imply: they contain references to any number
506 repository.</p></div>
507 <div class="paragraph"><p>One note: the special <tt>master</tt> head is the default branch, which is
510 point to the branch you are working on right now, and you always
515 valid, though.</p></div>
517 <table><tr>
520 </td>
521 <td class="content">An <em>object</em> is identified by its 160-bit SHA1 hash, aka <em>object name</em>,
522 and a reference to an object is always the 40-byte hex
524 subdirectory are expected to contain these hex references
526 expect to see a number of 41-byte files containing these
528 populating your tree.</td>
529 </tr></table>
530 </div>
532 <table><tr>
535 </td>
536 <td class="content">An advanced user may want to take a look at <a href="gitrepository-layout.html">gitrepository-layout(5)</a>
537 after finishing this tutorial.</td>
538 </tr></table>
539 </div>
540 <div class="paragraph"><p>You have now created your first git repository. Of course, since it’s
542 </div>
545 <div class="paragraph"><p>We’ll keep this simple and stupid, so we’ll start off with populating a
546 few trivial files just to get a feel for it.</p></div>
547 <div class="paragraph"><p>Start off with just creating any random files that you want to maintain
548 in your git repository. We’ll start off with a few bad examples, just to
549 get a feel for how this works:</p></div>
554 </div></div>
555 <div class="paragraph"><p>you have now created two files in your working tree (aka <em>working directory</em>),
556 but to actually check in your hard work, you will have to go through two steps:</p></div>
558 <li>
559 <p>
561 working tree state.
562 </p>
563 </li>
564 <li>
565 <p>
566 commit that index file as an object.
567 </p>
568 </li>
569 </ul></div>
570 <div class="paragraph"><p>The first step is trivial: when you want to tell git about any changes
572 program normally just takes a list of filenames you want to update, but
573 to avoid trivial mistakes, it refuses to add new entries to the index
574 (or remove existing ones) unless you explicitly tell it that you’re
577 <div class="paragraph"><p>So to populate the index with the two files you just created, you can do</p></div>
581 </div></div>
584 you’ll notice that git will have added two new objects to the object
585 database. If you did exactly the steps above, you should now be able to do</p></div>
589 </div></div>
595 </div></div>
596 <div class="paragraph"><p>which correspond with the objects with names of <tt>557db…</tt> and
598 <div class="paragraph"><p>If you want to, you can use <em>git cat-file</em> to look at those objects, but
603 </div></div>
604 <div class="paragraph"><p>where the <tt>-t</tt> tells <em>git cat-file</em> to tell you what the "type" of the
605 object is. git will tell you that you have a "blob" object (i.e., just a
606 regular file), and you can see the contents with</p></div>
610 </div></div>
611 <div class="paragraph"><p>which will print out "Hello World". The object <tt>557db03</tt> is nothing
614 <table><tr>
617 </td>
621 we just looked at will never change. Objects are immutable.</td>
622 </tr></table>
623 </div>
625 <table><tr>
628 </td>
630 abbreviate the object name to only the first several
631 hexadecimal digits in most places.</td>
632 </tr></table>
633 </div>
634 <div class="paragraph"><p>Anyway, as we mentioned previously, you normally never actually take a
635 look at the objects themselves, and typing long 40-character hex
636 names is not something you’d normally want to do. The above digression
638 actually saved away the contents of your files into the git object
639 database.</p></div>
640 <div class="paragraph"><p>Updating the index did something else too: it created a <tt>.git/index</tt>
641 file. This is the index that describes your current working tree, and
642 something you should be very aware of. Again, you normally never worry
643 about the index file itself, but you should be aware of the fact that
644 you have not actually really "checked in" your files into git so far,
646 <div class="paragraph"><p>However, since git knows about them, you can now start using some of the
647 most basic git commands to manipulate the files or look at their status.</p></div>
648 <div class="paragraph"><p>In particular, let’s not even check in the two files into git yet, we’ll
653 </div></div>
654 <div class="paragraph"><p>and you can now, since you told git about the previous state of <tt>hello</tt>, ask
655 git what has changed in the tree compared to your old index, using the
660 </div></div>
661 <div class="paragraph"><p>Oops. That wasn’t very readable. It just spit out its own internal
663 that it has noticed that "hello" has been modified, and that the old object
664 contents it had have been replaced with something else.</p></div>
665 <div class="paragraph"><p>To make it readable, we can tell <em>git diff-files</em> to output the
669 <pre><tt>$ git diff-files -p
670 diff --git a/hello b/hello
672 --- a/hello
673 +++ b/hello
675 Hello World
676 +It's a new day for git</tt></pre>
677 </div></div>
678 <div class="paragraph"><p>i.e. the diff of the change we caused by adding another line to <tt>hello</tt>.</p></div>
679 <div class="paragraph"><p>In other words, <em>git diff-files</em> always shows us the difference between
680 what is recorded in the index, and what is currently in the working
682 <div class="paragraph"><p>A common shorthand for <tt>git diff-files -p</tt> is to just write <tt>git
686 <pre><tt>$ git diff
687 diff --git a/hello b/hello
689 --- a/hello
690 +++ b/hello
692 Hello World
693 +It's a new day for git</tt></pre>
694 </div></div>
695 </div>
698 <div class="paragraph"><p>Now, we want to go to the next stage in git, which is to take the files
699 that git knows about in the index, and commit them as a real tree. We do
702 tree was all about, along with information of how we came to that state.</p></div>
703 <div class="paragraph"><p>Creating a tree object is trivial, and is done with <em>git write-tree</em>.
705 current index state, and write an object that describes that whole
706 index. In other words, we’re now tying together all the different
707 filenames with their contents (and their permissions), and we’re
712 </div></div>
713 <div class="paragraph"><p>and this will just output the name of the resulting tree, in this case
718 </div></div>
724 <div class="paragraph"><p>However — normally you’d never use <em>git write-tree</em> on its own, because
725 normally you always commit a tree into a commit object using the
729 <div class="paragraph"><p><em>git commit-tree</em> normally takes several arguments — it wants to know
731 ever in this new repository, and it has no parents, we only need to pass in
733 commit message on its standard input, and it will write out the resulting
734 object name for the commit to its standard output.</p></div>
737 the reference to the top-of-tree of the master branch, and since
739 all with a sequence of simple shell commands:</p></div>
742 <pre><tt>$ tree=$(git write-tree)
743 $ commit=$(echo 'Initial commit' | git commit-tree $tree)
744 $ git update-ref HEAD $commit</tt></pre>
745 </div></div>
748 all later commits will be parented on top of an earlier commit.</p></div>
749 <div class="paragraph"><p>Again, normally you’d never actually do this by hand. There is a
752 instead, and it would have done the above magic scripting for you.</p></div>
753 </div>
756 <div class="paragraph"><p>Remember how we did the <em>git update-index</em> on file <tt>hello</tt> and then we
758 state we saved in the index file?</p></div>
759 <div class="paragraph"><p>Further, remember how I said that <em>git write-tree</em> writes the contents
761 fact the <strong>original</strong> contents of the file <tt>hello</tt>, not the new ones. We did
762 that on purpose, to show the difference between the index state, and the
763 state in the working tree, and how they don’t have to match, even
764 when we commit things.</p></div>
765 <div class="paragraph"><p>As before, if we do <tt>git diff-files -p</tt> in our git-tutorial project,
766 we’ll still see the same difference we saw last time: the index file
767 hasn’t changed by the act of committing anything. However, now that we
768 have committed something, we can also learn to use a new command:
770 <div class="paragraph"><p>Unlike <em>git diff-files</em>, which showed the difference between the index
774 against, and before we did the commit, we couldn’t do that, because we
780 </div></div>
781 <div class="paragraph"><p>(where <tt>-p</tt> has the same meaning as it did in <em>git diff-files</em>), and it
782 will show us the same difference, but for a totally different reason.
783 Now we’re comparing the working tree not against the index file,
784 but against the tree we just wrote. It just so happens that those two
785 are obviously the same, so we get the same result.</p></div>
786 <div class="paragraph"><p>Again, because this is a common operation, you can also just shorthand
787 it with</p></div>
791 </div></div>
793 <div class="paragraph"><p>In other words, <em>git diff-index</em> normally compares a tree against the
795 instead compare against just the index cache contents, and ignore the
796 current working tree state entirely. Since we just wrote the index
800 <table><tr>
803 </td>
806 comparisons, and saying that it compares a tree against the working
807 tree is thus not strictly accurate. In particular, the list of
811 come from the working tree or not.</p></div>
812 <div class="paragraph"><p>This is not hard to understand, as soon as you realize that git simply
813 never knows (or cares) about files that it is not told about
815 expects you to tell it what the files are, and that’s what the index
816 is there for.</p></div>
817 </td>
818 </tr></table>
819 </div>
820 <div class="paragraph"><p>However, our next step is to commit the <strong>change</strong> we did, and again, to
823 in the working tree that we want to commit, and we always have to
824 work through the index file, so the first thing we need to do is to
825 update the index cache:</p></div>
829 </div></div>
830 <div class="paragraph"><p>(note how we didn’t need the <tt>--add</tt> flag this time, since git knew
831 about the file already).</p></div>
832 <div class="paragraph"><p>Note what happens to the different <em>git diff-*</em> versions here.
835 current state is different from the state we committed. In fact, now
837 flag or not, since now the index is coherent with the working tree.</p></div>
838 <div class="paragraph"><p>Now, since we’ve updated <tt>hello</tt> in the index, we can commit the new
839 version. We could do it by writing the tree by hand again, and
847 </div></div>
848 <div class="paragraph"><p>which starts an editor for you to write the commit message and tells you
849 a bit about what you have done.</p></div>
850 <div class="paragraph"><p>Write whatever message you want, and all the lines that start with <em>#</em>
851 will be pruned out, and the rest will be used as the commit message for
852 the change. If you decide you don’t want to commit anything after all at
853 this point (you can continue to edit things and update the index), you
855 the change for you.</p></div>
856 <div class="paragraph"><p>You’ve now made your first real git commit. And if you’re interested in
858 it’s a few very simple shell scripts to generate the helpful (?) commit
859 message headers, and a few one-liners that actually do the
861 </div>
864 <div class="paragraph"><p>While creating changes is useful, it’s even more useful if you can tell
865 later what changed. The most useful command for this is another of the
867 <div class="paragraph"><p><em>git diff-tree</em> can be given two arbitrary trees, and it will tell you the
868 differences between them. Perhaps even more commonly, though, you can
869 give it just a single commit object, and it will figure out the parent
870 of that commit itself, and show the difference directly. Thus, to get
875 </div></div>
876 <div class="paragraph"><p>(again, <tt>-p</tt> means to show the difference as a human-readable patch),
879 <table><tr>
882 </td>
888 <pre><tt> diff-tree
889 +----+
890 | |
891 | |
892 V V
893 +-----------+
894 | Object DB |
895 | Backing |
896 | Store |
897 +-----------+
898 ^ ^
899 | |
900 | | diff-index --cached
901 | |
902 diff-index | V
903 | +-----------+
904 | | Index |
905 | | "cache" |
906 | +-----------+
907 | ^
908 | |
909 | | diff-files
910 | |
911 V V
912 +-----------+
913 | Working |
914 | Directory |
915 +-----------+</tt></pre>
916 </div></div>
917 </td>
918 </tr></table>
919 </div>
920 <div class="paragraph"><p>More interestingly, you can also give <em>git diff-tree</em> the <tt>--pretty</tt> flag,
921 which tells it to also show the commit message and author and date of the
922 commit, and you can tell it to show a whole series of diffs.
923 Alternatively, you can tell it to be "silent", and not show the diffs at
924 all, but just show the actual commit message.</p></div>
925 <div class="paragraph"><p>In fact, together with the <em>git rev-list</em> program (which generates a
928 included with git which does exactly this, and shows a log of recent
929 activities.</p></div>
930 <div class="paragraph"><p>To see the whole history of our pitiful little git-tutorial project, you
931 can do</p></div>
935 </div></div>
936 <div class="paragraph"><p>which shows just the log messages, or if we want to see the log together
937 with the associated patches use the more complex (and much more
938 powerful)</p></div>
942 </div></div>
944 short history.</p></div>
946 <table><tr>
949 </td>
951 If this is a problem because it is huge, you can hide it by setting
952 the log.showroot configuration variable to false. Having this, you
955 </tr></table>
956 </div>
957 <div class="paragraph"><p>With that, you should now be having some inkling of what git does, and
958 can explore on your own.</p></div>
960 <table><tr>
963 </td>
967 </tr></table>
968 </div>
969 </div>
972 <div class="paragraph"><p>In git, there are two kinds of tags, a "light" one, and an "annotated tag".</p></div>
973 <div class="paragraph"><p>A "light" tag is technically nothing more than a branch, except we put
975 So the simplest form of tag involves nothing more than</p></div>
979 </div></div>
980 <div class="paragraph"><p>which just writes the current <tt>HEAD</tt> into the <tt>.git/refs/tags/my-first-tag</tt>
981 file, after which point you can then use this symbolic name for that
982 particular state. You can, for example, do</p></div>
986 </div></div>
988 obviously be an empty diff, but if you continue to develop and commit
989 stuff, you can use your tag as an "anchor-point" to see what has changed
990 since you tagged it.</p></div>
991 <div class="paragraph"><p>An "annotated tag" is actually a real git object, and contains not only a
992 pointer to the state you want to tag, but also a small tag name and
993 message, along with optionally a PGP signature that says that yes,
994 you really did
1000 </div></div>
1001 <div class="paragraph"><p>which will sign the current <tt>HEAD</tt> (but you can also give it another
1002 argument that specifies the thing to tag, e.g., you could have tagged the
1005 like that, while the light-weight tags are useful for any marking you
1006 want to do — any time you decide that you want to remember a certain
1007 point, just create a private tag for it, and you have a nice symbolic
1008 name for the state at that point.</p></div>
1009 </div>
1012 <div class="paragraph"><p>git repositories are normally totally self-sufficient and relocatable.
1013 Unlike CVS, for example, there is no separate notion of
1016 subdirectory. There is nothing else. What you see is what you got.</p></div>
1018 <table><tr>
1021 </td>
1024 how normal projects work, and it’s really only meant for special uses.
1025 So the mental model of "the git information is always tied directly to
1028 </tr></table>
1029 </div>
1032 <li>
1033 <p>
1034 if you grow bored with the tutorial repository you created (or you’ve
1035 made a mistake and want to start all over), you can just do simple
1036 </p>
1040 </div></div>
1041 <div class="paragraph"><p>and it will be gone. There’s no external repository, and there’s no
1042 history outside the project you created.</p></div>
1043 </li>
1044 <li>
1045 <p>
1046 if you want to move or duplicate a git repository, you can do so. There
1048 create a copy of your repository (with all the full history that
1049 went along with it), you can do so with a regular
1051 </p>
1052 <div class="paragraph"><p>Note that when you’ve moved or copied a git repository, your git index
1053 file (which caches various information, notably some of the "stat"
1054 information for the files involved) will likely need to be refreshed.
1059 </div></div>
1060 <div class="paragraph"><p>in the new repository to make sure that the index file is up-to-date.</p></div>
1061 </li>
1062 </ul></div>
1066 <div class="paragraph"><p>When copying a remote repository, you’ll want to at a minimum update the
1067 index cache when you do this, and especially with other peoples'
1068 repositories you often want to make sure that the index cache is in some
1069 known state (you don’t know <strong>what</strong> they’ve done and not yet checked in),
1073 <pre><tt>$ git read-tree --reset HEAD
1074 $ git update-index --refresh</tt></pre>
1075 </div></div>
1076 <div class="paragraph"><p>which will force a total index re-build from the tree pointed to by <tt>HEAD</tt>.
1078 makes sure to match up all index entries with the checked-out files.
1079 If the original repository had uncommitted changes in its
1081 tells you they need to be updated.</p></div>
1086 </div></div>
1087 <div class="paragraph"><p>and in fact a lot of the common git command combinations can be scripted
1092 the basic git commands.</p></div>
1095 actual core git files. Such a repository usually doesn’t even have the
1097 repository.</p></div>
1098 <div class="paragraph"><p>To create your own local live copy of such a "raw" git repository, you’d
1099 first create your own subdirectory for the project, and then copy the
1104 <pre><tt>$ mkdir my-git
1105 $ cd my-git
1106 $ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git</tt></pre>
1107 </div></div>
1112 </div></div>
1113 <div class="paragraph"><p>to populate the index. However, now you have populated the index, and
1114 you have all the git internal files, but you will notice that you don’t
1115 actually have any of the working tree files to work on. To get
1120 </div></div>
1121 <div class="paragraph"><p>where the <tt>-u</tt> flag means that you want the checkout to keep the index
1122 up-to-date (so that you don’t have to refresh it afterward), and the
1125 flag first, to tell <em>git checkout-index</em> to <strong>force</strong> overwriting of any old
1126 files).</p></div>
1130 <pre><tt>$ git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git
1131 $ cd my-git
1132 $ git checkout</tt></pre>
1133 </div></div>
1136 repository, and checked it out.</p></div>
1137 </div>
1143 these object pointers.</p></div>
1145 point in the project history, and just writing the SHA1 name of that
1147 want (and indeed, subdirectories), but the convention is that the
1149 and nothing enforces it.</p></div>
1150 <div class="paragraph"><p>To show that as an example, let’s go back to the git-tutorial repository we
1151 used earlier, and create a branch in it. You do that by simply just
1152 saying that you want to check out a new branch:</p></div>
1156 </div></div>
1157 <div class="paragraph"><p>will create a new branch based at the current <tt>HEAD</tt> position, and switch
1158 to it.</p></div>
1160 <table><tr>
1163 </td>
1172 </div></div>
1173 <div class="paragraph"><p>and it would create the new branch <tt>mybranch</tt> at the earlier commit,
1174 and check out the state at that time.</p></div>
1175 </td>
1176 </tr></table>
1177 </div>
1178 <div class="paragraph"><p>You can always just jump back to your original <tt>master</tt> branch by doing</p></div>
1182 </div></div>
1184 branch you happen to be on, a simple</p></div>
1188 </div></div>
1190 you have, you can say</p></div>
1194 </div></div>
1195 <div class="paragraph"><p>which used to be nothing more than a simple script around <tt>ls .git/refs/heads</tt>.
1196 There will be an asterisk in front of the branch you are currently on.</p></div>
1197 <div class="paragraph"><p>Sometimes you may wish to create a new branch <em>without</em> actually
1198 checking it out and switching to it. If so, just use the command</p></div>
1202 </div></div>
1203 <div class="paragraph"><p>which will simply <em>create</em> the branch, but will not do anything further.
1204 You can then later — once you decide that you want to actually develop
1206 with the branchname as the argument.</p></div>
1207 </div>
1211 experimental) work in it, and eventually merge it back to the main
1214 that branch, and do some work there.</p></div>
1217 <pre><tt>$ git checkout mybranch
1220 </div></div>
1221 <div class="paragraph"><p>Here, we just added another line to <tt>hello</tt>, and we used a shorthand for
1226 commit log message from the command line.</p></div>
1227 <div class="paragraph"><p>Now, to make it a bit more interesting, let’s assume that somebody else
1228 does some work in the original branch, and simulate that by going back
1229 to the master branch, and editing the same file differently there:</p></div>
1233 </div></div>
1234 <div class="paragraph"><p>Here, take a moment to look at the contents of <tt>hello</tt>, and notice how they
1235 don’t contain the work we just did in <tt>mybranch</tt> — because that work
1242 </div></div>
1243 <div class="paragraph"><p>since the master branch is obviously in a much better mood.</p></div>
1244 <div class="paragraph"><p>Now, you’ve got two branches, and you decide that you want to merge the
1245 work done. Before we do that, let’s introduce a cool graphical tool that
1250 </div></div>
1251 <div class="paragraph"><p>will show you graphically both of your branches (that’s what the <tt>--all</tt>
1253 histories. You can also see exactly how they came to be from a common
1254 source.</p></div>
1255 <div class="paragraph"><p>Anyway, let’s exit <em>gitk</em> (<tt>^Q</tt> or the File menu), and decide that we want
1259 to resolve and what the merge is all about:</p></div>
1263 </div></div>
1264 <div class="paragraph"><p>where the first argument is going to be used as the commit message if
1265 the merge can be resolved automatically.</p></div>
1266 <div class="paragraph"><p>Now, in this case we’ve intentionally created a situation where the
1267 merge will need to be fixed up by hand, though, so git will do as much
1272 <pre><tt> Auto-merging hello
1273 CONFLICT (content): Merge conflict in hello
1274 Automatic merge failed; fix conflicts and then commit the result.</tt></pre>
1275 </div></div>
1278 <div class="paragraph"><p>Not to worry. It left the (trivial) conflict in <tt>hello</tt> in the same form you
1284 <pre><tt>Hello World
1285 It's a new day for git
1286 Play, play, play
1287 Work, work, work</tt></pre>
1288 </div></div>
1289 <div class="paragraph"><p>and once you’re happy with your manual merge, just do a</p></div>
1293 </div></div>
1294 <div class="paragraph"><p>which will very loudly warn you that you’re now committing a merge
1295 (which is correct, so never mind), and you can write a small merge
1297 <div class="paragraph"><p>After you’re done, start up <tt>gitk --all</tt> to see graphically what the
1299 switch to it, and continue to work with it if you want to. The
1303 <div class="paragraph"><p>Another useful tool, especially if you do not always work in X-Window
1308 * [master] Merge work in mybranch
1309 ! [mybranch] Some work.
1310 --
1311 - [master] Merge work in mybranch
1312 *+ [mybranch] Some work.
1313 * [master^] Some fun.</tt></pre>
1314 </div></div>
1316 and the first line of the commit log message from their
1319 the later output lines is used to show commits contained in the
1321 branch. Three commits are shown along with their log messages.
1327 commits from the master branch. The string inside brackets
1328 before the commit log message is a short name you can use to
1332 see more complex cases.</p></div>
1334 <table><tr>
1337 </td>
1338 <td class="content">Without the <em>--more=1</em> option, <em>git show-branch</em> would not output the
1340 both <em>master</em> and <em>mybranch</em> tips. Please see <a href="git-show-branch.html">git-show-branch(1)</a>
1341 for details.</td>
1342 </tr></table>
1343 </div>
1345 <table><tr>
1348 </td>
1349 <td class="content">If there were more commits on the <em>master</em> branch after the merge, the
1352 merge commit visible in this case.</td>
1353 </tr></table>
1354 </div>
1361 <pre><tt>$ git checkout mybranch
1363 </div></div>
1365 would be different)</p></div>
1368 <pre><tt>Updating from ae3a2da... to a80b4aa....
1369 Fast-forward (no commit created; -m option ignored)
1370 example | 1 +
1371 hello | 1 +
1373 </div></div>
1376 not actually do a merge. Instead, it just updated the top of
1383 <pre><tt>$ git show-branch master mybranch
1384 ! [master] Merge work in mybranch
1385 * [mybranch] Merge work in mybranch
1386 --
1387 -- [master] Merge work in mybranch</tt></pre>
1388 </div></div>
1389 </div>
1392 <div class="paragraph"><p>It’s usually much more common that you merge with somebody else than
1393 merging with your own branches, so it’s worth pointing out that git
1394 makes that very easy too, and in fact, it’s not that different from
1396 more than "fetch the work from a remote repository into a temporary tag"
1403 </div></div>
1405 repository to download from:</p></div>
1408 Rsync
1409 </dt>
1410 <dd>
1411 <p>
1413 </p>
1415 but is completely unaware of what git does, and can produce
1416 unexpected results when you download from the public repository
1418 transport. Most notably, it could update the files under
1421 obtain head commit object name while that object itself is still
1422 not available in the repository. For this reason, it is
1423 considered deprecated.</p></div>
1424 </dd>
1426 SSH
1427 </dt>
1428 <dd>
1429 <p>
1431 </p>
1435 remote machine. It finds out the set of objects the other side
1436 lacks by exchanging the head commits both ends have and
1437 transfers (close to) minimum set of objects. It is by far the
1438 most efficient way to exchange git objects between repositories.</p></div>
1439 </dd>
1441 Local directory
1442 </dt>
1443 <dd>
1444 <p>
1446 </p>
1447 <div class="paragraph"><p>This transport is the same as SSH transport but uses <em>sh</em> to run
1448 both ends on the local machine instead of running other end on
1450 </dd>
1452 git Native
1453 </dt>
1454 <dd>
1455 <p>
1457 </p>
1459 transport, it finds out the set of objects the downstream side
1460 lacks and transfers (close to) minimum set of objects.</p></div>
1461 </dd>
1463 HTTP(S)
1464 </dt>
1465 <dd>
1466 <p>
1468 </p>
1470 first obtains the topmost commit object name from the remote site
1472 and then tries to obtain the
1474 using the object name of that commit object. Then it reads the
1475 commit object to find out its parent commits and the associate
1476 tree object; it repeats this process until it gets all the
1477 necessary objects. Because of this behavior, they are
1480 transports</em>, because they do not require any git aware smart
1481 server like git Native transport does. Any stock HTTP server
1482 that does not even support directory index would suffice. But
1484 to help dumb transport downloaders.</p></div>
1485 </dd>
1486 </dl></div>
1488 with your current branch.</p></div>
1489 <div class="paragraph"><p>However — it’s such a common thing to <tt>fetch</tt> and then
1491 simply do</p></div>
1495 </div></div>
1497 argument.</p></div>
1499 <table><tr>
1502 </td>
1504 keeping as many local repositories as you would like to have
1506 you merge between branches. The advantage of this approach is
1508 out and you may find it easier to switch back and forth if you
1509 juggle multiple lines of development simultaneously. Of
1510 course, you will pay the price of more disk usage to hold
1511 multiple working trees, but disk space is cheap these days.</td>
1512 </tr></table>
1513 </div>
1515 repository from time to time. As a short hand, you can store
1516 the remote repository URL in the local repository’s config file
1517 like this:</p></div>
1521 </div></div>
1522 <div class="paragraph"><p>and use the "linus" keyword with <em>git pull</em> instead of the full URL.</p></div>
1525 <li>
1526 <p>
1528 </p>
1529 </li>
1530 <li>
1531 <p>
1533 </p>
1534 </li>
1535 </ol></div>
1538 <li>
1539 <p>
1540 <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>
1541 </p>
1542 </li>
1543 <li>
1544 <p>
1545 <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>
1546 </p>
1547 </li>
1548 </ol></div>
1549 </div>
1553 with the porcelain that isn’t flushing, but we so far did not
1554 talk about how the merge really works. If you are following
1559 and bring ourselves back to the pre-merge state:</p></div>
1563 ! [master] Merge work in mybranch
1564 * [mybranch] Merge work in mybranch
1565 --
1566 -- [master] Merge work in mybranch
1567 +* [master^2] Some work.
1568 +* [master^] Some fun.</tt></pre>
1569 </div></div>
1570 <div class="paragraph"><p>Remember, before running <em>git merge</em>, our <tt>master</tt> head was at
1575 <pre><tt>$ git checkout mybranch
1576 $ git reset --hard master^2
1577 $ git checkout master
1578 $ git reset --hard master^</tt></pre>
1579 </div></div>
1580 <div class="paragraph"><p>After rewinding, the commit structure should look like this:</p></div>
1583 <pre><tt>$ git show-branch
1584 * [master] Some fun.
1585 ! [mybranch] Some work.
1586 --
1587 * [master] Some fun.
1588 + [mybranch] Some work.
1589 *+ [master^] Initial commit</tt></pre>
1590 </div></div>
1592 <div class="paragraph"><p><tt>git merge</tt> command, when merging two branches, uses 3-way merge
1593 algorithm. First, it finds the common ancestor between them.
1598 </div></div>
1600 to the standard output, so we captured its output to a variable,
1601 because we will be using it in the next step. By the way, the common
1602 ancestor commit is the "Initial commit" commit in this case. You can
1603 tell it by:</p></div>
1606 <pre><tt>$ git name-rev --name-only --tags $mb
1607 my-first-tag</tt></pre>
1608 </div></div>
1610 this:</p></div>
1614 </div></div>
1615 <div class="paragraph"><p>This is the same <em>git read-tree</em> command we have already seen,
1616 but it takes three trees, unlike previous examples. This reads
1619 etc.). After reading three trees into three stages, the paths
1621 0. Also paths that are the same in two of three stages are
1624 changed from the common ancestor).</p></div>
1625 <div class="paragraph"><p>After <em>collapsing</em> operation, paths that are different in three
1626 trees are left in non-zero stages. At this point, you can
1627 inspect the index file with this command:</p></div>
1630 <pre><tt>$ git ls-files --stage
1635 </div></div>
1638 large projects, when only a small number of files change in one commit,
1640 fairly quickly, leaving only a handful of real changes in non-zero
1641 stages.</p></div>
1642 <div class="paragraph"><p>To look at only non-zero stages, use <tt>--unmerged</tt> flag:</p></div>
1645 <pre><tt>$ git ls-files --unmerged
1649 </div></div>
1651 file, using 3-way merge. This is done by giving
1656 <pre><tt>$ git merge-index git-merge-one-file hello
1657 Auto-merging hello
1658 ERROR: Merge conflict in hello
1659 fatal: merge program failed</tt></pre>
1660 </div></div>
1662 describe those three versions, and is responsible to leave the
1663 merge results in the working tree.
1664 It is a fairly straightforward shell script, and
1667 conflicts, and the merge result with conflict marks is left in
1668 the working tree.. This can be seen if you run <tt>ls-files
1672 <pre><tt>$ git ls-files --stage
1677 </div></div>
1683 </div>
1686 <div class="paragraph"><p>So, we can use somebody else’s work from a remote repository, but
1688 it?</p></div>
1692 people to pull from it, but in practice that is not the way
1693 things are usually done. A recommended way is to have a public
1694 repository, make it reachable by other people, and when the
1695 changes you made in your primary working tree are in good shape,
1696 update the public repository from it. This is often called
1699 <table><tr>
1702 </td>
1705 </tr></table>
1706 </div>
1708 your remote (public) repository requires a write privilege on
1709 the remote machine. You need to have an SSH account there to
1712 machine that will house your public repository. This empty
1713 repository will be populated and be kept up-to-date by pushing
1714 into it later. Obviously, this repository creation needs to be
1715 done only once.</p></div>
1717 <table><tr>
1720 </td>
1723 on the remote machine. The communication between the two over
1724 the network internally uses an SSH connection.</td>
1725 </tr></table>
1726 </div>
1727 <div class="paragraph"><p>Your private repository’s git directory is usually <tt>.git</tt>, but
1728 your public repository is often named after the project name,
1731 an empty directory:</p></div>
1735 </div></div>
1742 </div></div>
1744 changes to be pulled via the transport of your choice. Also
1748 <table><tr>
1751 </td>
1753 shell when you directly run programs; what this means is that if
1757 </tr></table>
1758 </div>
1760 <table><tr>
1763 </td>
1765 you should do <tt>mv my-git.git/hooks/post-update.sample
1766 my-git.git/hooks/post-update</tt> at this point.
1767 This makes sure that every time you push into this
1769 </tr></table>
1770 </div>
1772 Come back to the machine you have your private repository. From
1773 there, run this command:</p></div>
1777 </div></div>
1780 from them in your current repository.</p></div>
1782 repository. Kernel.org mirror network takes care of the
1783 propagation to other publicly visible machines:</p></div>
1787 </div></div>
1788 </div>
1791 <div class="paragraph"><p>Earlier, we saw that one file under <tt>.git/objects/??/</tt> directory
1792 is stored for each git object you create. This representation
1793 is efficient to create atomically and safely, but
1794 not so convenient to transport over the network. Since git objects are
1795 immutable once they are created, there is a way to optimize the
1800 </div></div>
1805 directory.</p></div>
1807 <table><tr>
1810 </td>
1811 <td class="content">You will see two files, <tt>pack-*.pack</tt> and <tt>pack-*.idx</tt>,
1813 each other, and if you ever copy them by hand to a different
1814 repository for whatever reason, you should make sure you copy
1815 them together. The former holds all the data from the objects
1816 in the pack, and the latter holds the index for random
1817 access.</td>
1818 </tr></table>
1819 </div>
1821 detect if you have a corrupt pack, but do not worry too much.
1822 Our programs are always perfect ;-).</p></div>
1824 unpacked objects that are contained in the pack file anymore.</p></div>
1828 </div></div>
1830 <div class="paragraph"><p>You can try running <tt>find .git/objects -type f</tt> before and after
1832 count-objects</tt> would tell you how many unpacked objects are in
1833 your repository and how much space they are consuming.</p></div>
1835 <table><tr>
1838 </td>
1840 packed repository may contain relatively few objects in a
1841 relatively large pack. If you expect many HTTP pulls from your
1842 public repository you might want to repack & prune often, or
1843 never.</td>
1844 </tr></table>
1845 </div>
1847 "Nothing new to pack.". Once you continue your development and
1849 new pack, that contains objects created since you packed your
1850 repository the last time. We recommend that you pack your project
1851 soon after the initial import (unless you are starting your
1853 while, depending on how active your project is.</p></div>
1854 <div class="paragraph"><p>When a repository is synchronized via <tt>git push</tt> and <tt>git pull</tt>
1855 objects packed in the source repository are usually stored
1856 unpacked in the destination, unless rsync transport is used.
1857 While this allows you to use different packing strategies on
1858 both ends, it also means you may need to repack both
1859 repositories every once in a while.</p></div>
1860 </div>
1864 convenient to organize your project with an informal hierarchy
1865 of developers. Linux kernel development is run this way. There
1867 <a href="http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf">Randy Dunlap’s presentation</a>.</p></div>
1868 <div class="paragraph"><p>It should be stressed that this hierarchy is purely <strong>informal</strong>.
1869 There is nothing fundamental in git that enforces the "chain of
1870 patch flow" this hierarchy implies. You do not have to pull
1871 from only one remote repository.</p></div>
1872 <div class="paragraph"><p>A recommended workflow for a "project lead" goes like this:</p></div>
1874 <li>
1875 <p>
1876 Prepare your primary repository on your local machine. Your
1877 work is done there.
1878 </p>
1879 </li>
1880 <li>
1881 <p>
1882 Prepare a public repository accessible to others.
1883 </p>
1885 transport protocols (HTTP), you need to keep this repository
1889 but you need to manually enable the hook with
1892 </li>
1893 <li>
1894 <p>
1895 Push into the public repository from your primary
1896 repository.
1897 </p>
1898 </li>
1899 <li>
1900 <p>
1902 pack that contains the initial set of objects as the
1904 used for pulling from your repository supports packed
1905 repositories.
1906 </p>
1907 </li>
1908 <li>
1909 <p>
1910 Keep working in your primary repository. Your changes
1911 include modifications of your own, patches you receive via
1912 e-mails, and merges resulting from pulling the "public"
1913 repositories of your "subsystem maintainers".
1914 </p>
1915 <div class="paragraph"><p>You can repack this private repository whenever you feel like.</p></div>
1916 </li>
1917 <li>
1918 <p>
1919 Push your changes to the public repository, and announce it
1920 to the public.
1921 </p>
1922 </li>
1923 <li>
1924 <p>
1926 Go back to step 5. and continue working.
1927 </p>
1928 </li>
1929 </ol></div>
1933 <li>
1934 <p>
1936 repository of the "project lead". The URL used for the
1937 initial cloning is stored in the remote.origin.url
1938 configuration variable.
1939 </p>
1940 </li>
1941 <li>
1942 <p>
1943 Prepare a public repository accessible to others, just like
1944 the "project lead" person does.
1945 </p>
1946 </li>
1947 <li>
1948 <p>
1949 Copy over the packed files from "project lead" public
1950 repository to your public repository, unless the "project
1951 lead" repository lives on the same machine as yours. In the
1953 point at the repository you are borrowing from.
1954 </p>
1955 </li>
1956 <li>
1957 <p>
1958 Push into the public repository from your primary
1960 transport used for pulling from your repository supports
1961 packed repositories.
1962 </p>
1963 </li>
1964 <li>
1965 <p>
1966 Keep working in your primary repository. Your changes
1967 include modifications of your own, patches you receive via
1968 e-mails, and merges resulting from pulling the "public"
1969 repositories of your "project lead" and possibly your
1970 "sub-subsystem maintainers".
1971 </p>
1973 like.</p></div>
1974 </li>
1975 <li>
1976 <p>
1977 Push your changes to your public repository, and ask your
1979 maintainers" to pull from it.
1980 </p>
1981 </li>
1982 <li>
1983 <p>
1985 Go back to step 5. and continue working.
1986 </p>
1987 </li>
1988 </ol></div>
1990 not have a "public" repository is somewhat different. It goes
1991 like this:</p></div>
1993 <li>
1994 <p>
1997 maintainer", if you work on a subsystem). The URL used for
1998 the initial cloning is stored in the remote.origin.url
1999 configuration variable.
2000 </p>
2001 </li>
2002 <li>
2003 <p>
2005 </p>
2006 </li>
2007 <li>
2008 <p>
2010 upstream every once in a while. This does only the first
2013 </p>
2014 </li>
2015 <li>
2016 <p>
2019 unmerged changes forward to the updated upstream.
2020 </p>
2021 </li>
2022 <li>
2023 <p>
2025 submission to your upstream and send it out. Go back to
2026 step 2. and continue.
2027 </p>
2028 </li>
2029 </ol></div>
2030 </div>
2031 <h2 id="_working_with_others_shared_repository_style">Working with Others, Shared Repository Style</h2>
2034 suggested in the previous section may be new to you. You do not
2035 have to worry. git supports "shared public repository" style of
2036 cooperation you are probably more familiar with as well.</p></div>
2037 <div class="paragraph"><p>See <a href="gitcvs-migration.html">gitcvs-migration(7)</a> for the details.</p></div>
2038 </div>
2042 a time. It is easy to manage those more-or-less independent tasks
2043 using branches with git.</p></div>
2045 with "fun and work" example using two branches. The idea is the
2046 same if there are more than two branches. Let’s say you started
2048 branch, and two independent fixes in the "commit-fix" and
2052 <pre><tt>$ git show-branch
2053 ! [commit-fix] Fix commit message normalization.
2054 ! [diff-fix] Fix rename detection.
2055 * [master] Release candidate #1
2056 ---
2057 + [diff-fix] Fix rename detection.
2058 + [diff-fix~1] Better common substring algorithm.
2059 + [commit-fix] Fix commit message normalization.
2060 * [master] Release candidate #1
2062 </div></div>
2070 </div></div>
2074 <pre><tt>$ git show-branch
2075 ! [commit-fix] Fix commit message normalization.
2076 ! [diff-fix] Fix rename detection.
2077 * [master] Merge fix in commit-fix
2078 ---
2079 - [master] Merge fix in commit-fix
2080 + * [commit-fix] Fix commit message normalization.
2081 - [master~1] Merge fix in diff-fix
2082 +* [diff-fix] Fix rename detection.
2083 +* [diff-fix~1] Better common substring algorithm.
2086 </div></div>
2088 first and the other next, when what you have are a set of truly
2089 independent changes (if the order mattered, then they are not
2090 independent by definition). You could instead merge those two
2091 branches into the current branch at once. First let’s undo what
2092 we just did and start over. We would want to get the master
2097 </div></div>
2104 <pre><tt>$ git merge commit-fix diff-fix
2105 $ git show-branch
2106 ! [commit-fix] Fix commit message normalization.
2107 ! [diff-fix] Fix rename detection.
2108 * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
2109 ---
2110 - [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
2111 + * [commit-fix] Fix commit message normalization.
2112 +* [diff-fix] Fix rename detection.
2113 +* [diff-fix~1] Better common substring algorithm.
2116 </div></div>
2118 is a valid thing to do and often makes it easier to view the
2119 commit history if you are merging more than two independent
2120 changes at the same time. However, if you have merge conflicts
2121 with any of the branches you are merging in and need to hand
2122 resolve, that is an indication that the development happened in
2123 those branches were not independent after all, and you should
2124 merge two at a time, documenting how you resolved the conflicts,
2125 and the reason why you preferred changes made in one side over
2126 the other. Otherwise it would make the project history harder
2127 to follow, not easier.</p></div>
2128 </div>
2137 </div>
2141 </div>
2145 </div>
2146 </div>
2147 </body>
2148 </html>