| blob | 9176a2caecb79217c793bcd631288a16abde1af4 |
4 <head>
8 /* Debug borders */
10 /*
11 border: 1px solid red;
12 */
13 }
15 body {
17 }
19 a {
22 }
25 }
27 em {
29 }
31 strong {
33 }
35 tt {
37 }
45 }
49 }
50 h2 {
52 }
53 h3 {
55 }
56 h3 + * {
58 }
63 }
65 hr {
67 }
69 p {
72 }
74 pre {
77 }
79 span#author {
84 }
85 span#email {
86 }
87 span#revision {
89 }
91 div#footer {
97 }
98 div#footer-text {
101 }
102 div#footer-badges {
105 }
107 div#preamble,
114 }
118 }
122 }
124 /* Block element titles. */
131 }
134 }
138 }
141 }
144 }
150 }
154 }
159 }
163 }
167 }
170 }
179 }
183 }
188 }
192 }
198 dl {
201 }
202 dt {
206 }
209 }
213 }
216 }
220 }
221 thead {
224 }
225 tfoot {
227 }
232 }
235 }
240 }
243 }
247 }
249 div#toctitle {
256 }
261 }
265 }
269 }
273 }
275 /* Workarounds for IE6's broken and incomplete CSS2. */
281 }
287 }
293 }
297 }
302 }
304 /* IE6 sets dynamically generated links as visited. */
306 </style>
308 </head>
309 <body>
311 <h1>
312 gitcore-tutorial(7) Manual Page
313 </h1>
316 <p>gitcore-tutorial -
317 A git core tutorial for developers
318 </p>
319 </div>
320 </div>
324 </div>
328 work with a git repository.</p></div>
330 to start with "A Tutorial Introduction to GIT" (<a href="gittutorial.html">gittutorial(7)</a>) or
333 you want to understand git's internals.</p></div>
335 interfaces on top of it called "porcelain". You may not want to use the
336 plumbing directly very often, but it can be good to know what the
337 plumbing does for when the porcelain isn't flushing.</p></div>
339 commands were shell scripts. For simplicity, it still uses them as
340 examples to illustrate how plumbing is fit together to form the
341 porcelain commands. The source tree includes some of these scripts in
342 contrib/examples/ for reference. Although these are not implemented as
343 shell scripts anymore, the description of what the plumbing layer
344 commands do is still valid.</p></div>
346 <table><tr>
349 </td>
351 skip on your first reading.</td>
352 </tr></table>
353 </div>
354 </div>
357 <div class="para"><p>Creating a new git repository couldn't be easier: all git repositories start
358 out empty, and the only thing you need to do is find yourself a
359 subdirectory that you want to use as a working tree - either an empty
360 one for a totally new project, or an existing working tree that you want
361 to import into git.</p></div>
364 To start up, create a subdirectory for it, change into that
368 <pre><tt>$ mkdir git-tutorial
369 $ cd git-tutorial
370 $ git init</tt></pre>
371 </div></div>
376 </div></div>
381 three entries, among other things:</p></div>
383 <li>
384 <p>
386 This is similar to a symbolic link and points at
388 </p>
389 <div class="para"><p>Don't worry about the fact that the file that the <tt>HEAD</tt> link points to
390 doesn't even exist yet — you haven't created the commit that will
392 </li>
393 <li>
394 <p>
396 objects of your project. You should never have any real reason to
397 look at the objects directly, but you might want to know that these
399 </p>
400 </li>
401 <li>
402 <p>
404 </p>
405 </li>
406 </ul></div>
409 exactly what their names imply: they contain references to any number
412 repository.</p></div>
416 point to the branch you are working on right now, and you always
421 valid, though.</p></div>
423 <table><tr>
426 </td>
427 <td class="content">An <em>object</em> is identified by its 160-bit SHA1 hash, aka <em>object name</em>,
428 and a reference to an object is always the 40-byte hex
430 subdirectory are expected to contain these hex references
432 expect to see a number of 41-byte files containing these
434 populating your tree.</td>
435 </tr></table>
436 </div>
438 <table><tr>
441 </td>
442 <td class="content">An advanced user may want to take a look at <a href="gitrepository-layout.html">gitrepository-layout(5)</a>
443 after finishing this tutorial.</td>
444 </tr></table>
445 </div>
447 empty, that's not very useful, so let's start populating it with data.</p></div>
448 </div>
452 few trivial files just to get a feel for it.</p></div>
454 in your git repository. We'll start off with a few bad examples, just to
455 get a feel for how this works:</p></div>
460 </div></div>
461 <div class="para"><p>you have now created two files in your working tree (aka <em>working directory</em>),
462 but to actually check in your hard work, you will have to go through two steps:</p></div>
464 <li>
465 <p>
467 working tree state.
468 </p>
469 </li>
470 <li>
471 <p>
472 commit that index file as an object.
473 </p>
474 </li>
475 </ul></div>
478 program normally just takes a list of filenames you want to update, but
479 to avoid trivial mistakes, it refuses to add new entries to the index
480 (or remove existing ones) unless you explicitly tell it that you're
483 <div class="para"><p>So to populate the index with the two files you just created, you can do</p></div>
487 </div></div>
490 you'll notice that git will have added two new objects to the object
491 database. If you did exactly the steps above, you should now be able to do</p></div>
495 </div></div>
501 </div></div>
504 <div class="para"><p>If you want to, you can use <em>git cat-file</em> to look at those objects, but
505 you'll have to use the object name, not the filename of the object:</p></div>
509 </div></div>
510 <div class="para"><p>where the <tt>-t</tt> tells <em>git cat-file</em> to tell you what the "type" of the
511 object is. git will tell you that you have a "blob" object (i.e., just a
512 regular file), and you can see the contents with</p></div>
516 </div></div>
520 <table><tr>
523 </td>
527 we just looked at will never change. Objects are immutable.</td>
528 </tr></table>
529 </div>
531 <table><tr>
534 </td>
536 abbreviate the object name to only the first several
537 hexadecimal digits in most places.</td>
538 </tr></table>
539 </div>
541 look at the objects themselves, and typing long 40-character hex
542 names is not something you'd normally want to do. The above digression
544 actually saved away the contents of your files into the git object
545 database.</p></div>
546 <div class="para"><p>Updating the index did something else too: it created a <tt>.git/index</tt>
547 file. This is the index that describes your current working tree, and
548 something you should be very aware of. Again, you normally never worry
549 about the index file itself, but you should be aware of the fact that
550 you have not actually really "checked in" your files into git so far,
553 most basic git commands to manipulate the files or look at their status.</p></div>
559 </div></div>
560 <div class="para"><p>and you can now, since you told git about the previous state of <tt>hello</tt>, ask
561 git what has changed in the tree compared to your old index, using the
566 </div></div>
569 that it has noticed that "hello" has been modified, and that the old object
570 contents it had have been replaced with something else.</p></div>
575 <pre><tt>$ git diff-files -p
576 diff --git a/hello b/hello
578 --- a/hello
579 +++ b/hello
581 Hello World
582 +It's a new day for git</tt></pre>
583 </div></div>
584 <div class="para"><p>i.e. the diff of the change we caused by adding another line to <tt>hello</tt>.</p></div>
585 <div class="para"><p>In other words, <em>git diff-files</em> always shows us the difference between
586 what is recorded in the index, and what is currently in the working
587 tree. That's very useful.</p></div>
592 <pre><tt>$ git diff
593 diff --git a/hello b/hello
595 --- a/hello
596 +++ b/hello
598 Hello World
599 +It's a new day for git</tt></pre>
600 </div></div>
601 </div>
605 that git knows about in the index, and commit them as a real tree. We do
608 tree was all about, along with information of how we came to that state.</p></div>
609 <div class="para"><p>Creating a tree object is trivial, and is done with <em>git write-tree</em>.
611 current index state, and write an object that describes that whole
612 index. In other words, we're now tying together all the different
613 filenames with their contents (and their permissions), and we're
618 </div></div>
620 (if you have done exactly as I've described) it should be</p></div>
624 </div></div>
629 mainly a binary mess, so that's less interesting).</p></div>
630 <div class="para"><p>However — normally you'd never use <em>git write-tree</em> on its own, because
631 normally you always commit a tree into a commit object using the
635 <div class="para"><p><em>git commit-tree</em> normally takes several arguments — it wants to know
637 ever in this new repository, and it has no parents, we only need to pass in
639 commit message on its standard input, and it will write out the resulting
640 object name for the commit to its standard output.</p></div>
643 the reference to the top-of-tree of the master branch, and since
645 all with a sequence of simple shell commands:</p></div>
648 <pre><tt>$ tree=$(git write-tree)
649 $ commit=$(echo 'Initial commit' | git commit-tree $tree)
650 $ git update-ref HEAD $commit</tt></pre>
651 </div></div>
654 all later commits will be parented on top of an earlier commit.</p></div>
658 instead, and it would have done the above magic scripting for you.</p></div>
659 </div>
662 <div class="para"><p>Remember how we did the <em>git update-index</em> on file <tt>hello</tt> and then we
664 state we saved in the index file?</p></div>
665 <div class="para"><p>Further, remember how I said that <em>git write-tree</em> writes the contents
667 fact the <strong>original</strong> contents of the file <tt>hello</tt>, not the new ones. We did
668 that on purpose, to show the difference between the index state, and the
669 state in the working tree, and how they don't have to match, even
670 when we commit things.</p></div>
671 <div class="para"><p>As before, if we do <tt>git diff-files -p</tt> in our git-tutorial project,
672 we'll still see the same difference we saw last time: the index file
673 hasn't changed by the act of committing anything. However, now that we
674 have committed something, we can also learn to use a new command:
676 <div class="para"><p>Unlike <em>git diff-files</em>, which showed the difference between the index
680 against, and before we did the commit, we couldn't do that, because we
681 didn't have anything to diff against.</p></div>
686 </div></div>
687 <div class="para"><p>(where <tt>-p</tt> has the same meaning as it did in <em>git diff-files</em>), and it
688 will show us the same difference, but for a totally different reason.
689 Now we're comparing the working tree not against the index file,
690 but against the tree we just wrote. It just so happens that those two
691 are obviously the same, so we get the same result.</p></div>
693 it with</p></div>
697 </div></div>
699 <div class="para"><p>In other words, <em>git diff-index</em> normally compares a tree against the
701 instead compare against just the index cache contents, and ignore the
702 current working tree state entirely. Since we just wrote the index
704 an empty set of differences, and that's exactly what it does.</p></div>
706 <table><tr>
709 </td>
712 comparisons, and saying that it compares a tree against the working
713 tree is thus not strictly accurate. In particular, the list of
717 come from the working tree or not.</p></div>
719 never knows (or cares) about files that it is not told about
721 expects you to tell it what the files are, and that's what the index
722 is there for.</p></div>
723 </td>
724 </tr></table>
725 </div>
726 <div class="para"><p>However, our next step is to commit the <strong>change</strong> we did, and again, to
727 understand what's going on, keep in mind the difference between "working
729 in the working tree that we want to commit, and we always have to
730 work through the index file, so the first thing we need to do is to
731 update the index cache:</p></div>
735 </div></div>
737 about the file already).</p></div>
738 <div class="para"><p>Note what happens to the different <em>git diff-*</em> versions here. After
741 current state is different from the state we committed. In fact, now
743 flag or not, since now the index is coherent with the working tree.</p></div>
744 <div class="para"><p>Now, since we've updated <tt>hello</tt> in the index, we can commit the new
745 version. We could do it by writing the tree by hand again, and
748 this wasn't an initial commit any more), but you've done that once
749 already, so let's just use the helpful script this time:</p></div>
753 </div></div>
755 a bit about what you have done.</p></div>
756 <div class="para"><p>Write whatever message you want, and all the lines that start with <em>#</em>
757 will be pruned out, and the rest will be used as the commit message for
758 the change. If you decide you don't want to commit anything after all at
759 this point (you can continue to edit things and update the index), you
761 the change for you.</p></div>
764 it's a few very simple shell scripts to generate the helpful (?) commit
765 message headers, and a few one-liners that actually do the
767 </div>
771 later what changed. The most useful command for this is another of the
773 <div class="para"><p><em>git diff-tree</em> can be given two arbitrary trees, and it will tell you the
774 differences between them. Perhaps even more commonly, though, you can
775 give it just a single commit object, and it will figure out the parent
776 of that commit itself, and show the difference directly. Thus, to get
777 the same diff that we've already seen several times, we can now do</p></div>
781 </div></div>
782 <div class="para"><p>(again, <tt>-p</tt> means to show the difference as a human-readable patch),
785 <table><tr>
788 </td>
791 various diff-* commands compare things.</p></div>
794 <pre><tt> diff-tree
795 +----+
796 | |
797 | |
798 V V
799 +-----------+
800 | Object DB |
801 | Backing |
802 | Store |
803 +-----------+
804 ^ ^
805 | |
806 | | diff-index --cached
807 | |
808 diff-index | V
809 | +-----------+
810 | | Index |
811 | | "cache" |
812 | +-----------+
813 | ^
814 | |
815 | | diff-files
816 | |
817 V V
818 +-----------+
819 | Working |
820 | Directory |
821 +-----------+</tt></pre>
822 </div></div>
823 </td>
824 </tr></table>
825 </div>
826 <div class="para"><p>More interestingly, you can also give <em>git diff-tree</em> the <tt>--pretty</tt> flag,
827 which tells it to also show the commit message and author and date of the
828 commit, and you can tell it to show a whole series of diffs.
829 Alternatively, you can tell it to be "silent", and not show the diffs at
830 all, but just show the actual commit message.</p></div>
831 <div class="para"><p>In fact, together with the <em>git rev-list</em> program (which generates a
834 included with git which does exactly this, and shows a log of recent
835 activities.</p></div>
837 can do</p></div>
841 </div></div>
843 with the associated patches use the more complex (and much more
844 powerful)</p></div>
848 </div></div>
850 short history.</p></div>
852 <table><tr>
855 </td>
857 If this is a problem because it is huge, you can hide it by setting
858 the log.showroot configuration variable to false. Having this, you
861 </tr></table>
862 </div>
864 can explore on your own.</p></div>
866 <table><tr>
869 </td>
872 and `git-commit'.</td>
873 </tr></table>
874 </div>
875 </div>
878 <div class="para"><p>In git, there are two kinds of tags, a "light" one, and an "annotated tag".</p></div>
881 So the simplest form of tag involves nothing more than</p></div>
885 </div></div>
886 <div class="para"><p>which just writes the current <tt>HEAD</tt> into the <tt>.git/refs/tags/my-first-tag</tt>
887 file, after which point you can then use this symbolic name for that
888 particular state. You can, for example, do</p></div>
892 </div></div>
894 obviously be an empty diff, but if you continue to develop and commit
895 stuff, you can use your tag as an "anchor-point" to see what has changed
896 since you tagged it.</p></div>
898 pointer to the state you want to tag, but also a small tag name and
899 message, along with optionally a PGP signature that says that yes,
900 you really did
906 </div></div>
907 <div class="para"><p>which will sign the current <tt>HEAD</tt> (but you can also give it another
908 argument that specifies the thing to tag, e.g., you could have tagged the
911 like that, while the light-weight tags are useful for any marking you
912 want to do — any time you decide that you want to remember a certain
913 point, just create a private tag for it, and you have a nice symbolic
914 name for the state at that point.</p></div>
915 </div>
919 Unlike CVS, for example, there is no separate notion of
922 subdirectory. There is nothing else. What you see is what you got.</p></div>
924 <table><tr>
927 </td>
929 the directory that it tracks, but we'll ignore that for now: it's not
930 how normal projects work, and it's really only meant for special uses.
931 So the mental model of "the git information is always tied directly to
933 accurate, but it's a good model for all normal use.</td>
934 </tr></table>
935 </div>
938 <li>
939 <p>
940 if you grow bored with the tutorial repository you created (or you've
941 made a mistake and want to start all over), you can just do simple
942 </p>
946 </div></div>
948 history outside the project you created.</p></div>
949 </li>
950 <li>
951 <p>
952 if you want to move or duplicate a git repository, you can do so. There
954 create a copy of your repository (with all the full history that
955 went along with it), you can do so with a regular
957 </p>
959 file (which caches various information, notably some of the "stat"
960 information for the files involved) will likely need to be refreshed.
965 </div></div>
966 <div class="para"><p>in the new repository to make sure that the index file is up-to-date.</p></div>
967 </li>
968 </ul></div>
973 index cache when you do this, and especially with other peoples'
974 repositories you often want to make sure that the index cache is in some
979 <pre><tt>$ git read-tree --reset HEAD
980 $ git update-index --refresh</tt></pre>
981 </div></div>
982 <div class="para"><p>which will force a total index re-build from the tree pointed to by <tt>HEAD</tt>.
984 makes sure to match up all index entries with the checked-out files.
985 If the original repository had uncommitted changes in its
987 tells you they need to be updated.</p></div>
992 </div></div>
998 the basic git commands.</p></div>
1001 actual core git files. Such a repository usually doesn't even have the
1003 repository.</p></div>
1005 first create your own subdirectory for the project, and then copy the
1007 create your own copy of the git repository, you'd do the following</p></div>
1010 <pre><tt>$ mkdir my-git
1011 $ cd my-git
1012 $ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git</tt></pre>
1013 </div></div>
1018 </div></div>
1020 you have all the git internal files, but you will notice that you don't
1021 actually have any of the working tree files to work on. To get
1022 those, you'd check them out with</p></div>
1026 </div></div>
1027 <div class="para"><p>where the <tt>-u</tt> flag means that you want the checkout to keep the index
1028 up-to-date (so that you don't have to refresh it afterward), and the
1031 flag first, to tell <em>git checkout-index</em> to <strong>force</strong> overwriting of any old
1032 files).</p></div>
1036 <pre><tt>$ git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git
1037 $ cd my-git
1038 $ git checkout</tt></pre>
1039 </div></div>
1042 repository, and checked it out.</p></div>
1043 </div>
1049 these object pointers.</p></div>
1051 point in the project history, and just writing the SHA1 name of that
1053 want (and indeed, subdirectories), but the convention is that the
1055 and nothing enforces it.</p></div>
1056 <div class="para"><p>To show that as an example, let's go back to the git-tutorial repository we
1057 used earlier, and create a branch in it. You do that by simply just
1058 saying that you want to check out a new branch:</p></div>
1062 </div></div>
1063 <div class="para"><p>will create a new branch based at the current <tt>HEAD</tt> position, and switch
1064 to it.</p></div>
1066 <table><tr>
1069 </td>
1074 In other words, if you have an earlier tag or branch, you'd just do</p></div>
1078 </div></div>
1079 <div class="para"><p>and it would create the new branch <tt>mybranch</tt> at the earlier commit,
1080 and check out the state at that time.</p></div>
1081 </td>
1082 </tr></table>
1083 </div>
1084 <div class="para"><p>You can always just jump back to your original <tt>master</tt> branch by doing</p></div>
1088 </div></div>
1090 branch you happen to be on, a simple</p></div>
1094 </div></div>
1096 you have, you can say</p></div>
1100 </div></div>
1101 <div class="para"><p>which used to be nothing more than a simple script around <tt>ls .git/refs/heads</tt>.
1102 There will be an asterisk in front of the branch you are currently on.</p></div>
1104 checking it out and switching to it. If so, just use the command</p></div>
1108 </div></div>
1110 You can then later — once you decide that you want to actually develop
1112 with the branchname as the argument.</p></div>
1113 </div>
1117 experimental) work in it, and eventually merge it back to the main
1120 that branch, and do some work there.</p></div>
1123 <pre><tt>$ git checkout mybranch
1126 </div></div>
1127 <div class="para"><p>Here, we just added another line to <tt>hello</tt>, and we used a shorthand for
1132 commit log message from the command line.</p></div>
1134 does some work in the original branch, and simulate that by going back
1135 to the master branch, and editing the same file differently there:</p></div>
1139 </div></div>
1140 <div class="para"><p>Here, take a moment to look at the contents of <tt>hello</tt>, and notice how they
1148 </div></div>
1151 work done. Before we do that, let's introduce a cool graphical tool that
1152 helps you view what's going on:</p></div>
1156 </div></div>
1157 <div class="para"><p>will show you graphically both of your branches (that's what the <tt>--all</tt>
1159 histories. You can also see exactly how they came to be from a common
1160 source.</p></div>
1161 <div class="para"><p>Anyway, let's exit <em>gitk</em> (<tt>^Q</tt> or the File menu), and decide that we want
1165 to resolve and what the merge is all about:</p></div>
1169 </div></div>
1171 the merge can be resolved automatically.</p></div>
1173 merge will need to be fixed up by hand, though, so git will do as much
1178 <pre><tt> Auto-merging hello
1179 CONFLICT (content): Merge conflict in hello
1180 Automatic merge failed; fix conflicts and then commit the result.</tt></pre>
1181 </div></div>
1184 <div class="para"><p>Not to worry. It left the (trivial) conflict in <tt>hello</tt> in the same form you
1185 should already be well used to if you've ever used CVS, so let's just
1190 <pre><tt>Hello World
1191 It's a new day for git
1192 Play, play, play
1193 Work, work, work</tt></pre>
1194 </div></div>
1199 </div></div>
1201 (which is correct, so never mind), and you can write a small merge
1203 <div class="para"><p>After you're done, start up <tt>gitk --all</tt> to see graphically what the
1205 switch to it, and continue to work with it if you want to. The
1208 have to do _that_ merge again.</p></div>
1214 * [master] Merge work in mybranch
1215 ! [mybranch] Some work.
1216 --
1217 - [master] Merge work in mybranch
1218 *+ [mybranch] Some work.
1219 * [master^] Some fun.</tt></pre>
1220 </div></div>
1222 and the first line of the commit log message from their
1225 the later output lines is used to show commits contained in the
1227 branch. Three commits are shown along with their log messages.
1233 commits from the master branch. The string inside brackets
1234 before the commit log message is a short name you can use to
1238 see more complex cases.</p></div>
1240 <table><tr>
1243 </td>
1244 <td class="content">Without the <em>--more=1</em> option, <em>git show-branch</em> would not output the
1246 both <em>master</em> and <em>mybranch</em> tips. Please see <a href="git-show-branch.html">git-show-branch(1)</a>
1247 for details.</td>
1248 </tr></table>
1249 </div>
1251 <table><tr>
1254 </td>
1255 <td class="content">If there were more commits on the <em>master</em> branch after the merge, the
1258 merge commit visible in this case.</td>
1259 </tr></table>
1260 </div>
1267 <pre><tt>$ git checkout mybranch
1269 </div></div>
1271 would be different)</p></div>
1274 <pre><tt>Updating from ae3a2da... to a80b4aa....
1275 Fast-forward (no commit created; -m option ignored)
1276 example | 1 +
1277 hello | 1 +
1279 </div></div>
1282 not actually do a merge. Instead, it just updated the top of
1289 <pre><tt>$ git show-branch master mybranch
1290 ! [master] Merge work in mybranch
1291 * [mybranch] Merge work in mybranch
1292 --
1293 -- [master] Merge work in mybranch</tt></pre>
1294 </div></div>
1295 </div>
1299 merging with your own branches, so it's worth pointing out that git
1300 makes that very easy too, and in fact, it's not that different from
1302 more than "fetch the work from a remote repository into a temporary tag"
1309 </div></div>
1311 repository to download from:</p></div>
1313 <dt>
1314 Rsync
1315 </dt>
1316 <dd>
1317 <p>
1319 </p>
1321 but is completely unaware of what git does, and can produce
1322 unexpected results when you download from the public repository
1324 transport. Most notably, it could update the files under
1327 obtain head commit object name while that object itself is still
1328 not available in the repository. For this reason, it is
1329 considered deprecated.</p></div>
1330 </dd>
1331 <dt>
1332 SSH
1333 </dt>
1334 <dd>
1335 <p>
1337 </p>
1341 remote machine. It finds out the set of objects the other side
1342 lacks by exchanging the head commits both ends have and
1343 transfers (close to) minimum set of objects. It is by far the
1344 most efficient way to exchange git objects between repositories.</p></div>
1345 </dd>
1346 <dt>
1347 Local directory
1348 </dt>
1349 <dd>
1350 <p>
1352 </p>
1354 both ends on the local machine instead of running other end on
1356 </dd>
1357 <dt>
1358 git Native
1359 </dt>
1360 <dd>
1361 <p>
1363 </p>
1365 transport, it finds out the set of objects the downstream side
1366 lacks and transfers (close to) minimum set of objects.</p></div>
1367 </dd>
1368 <dt>
1369 HTTP(S)
1370 </dt>
1371 <dd>
1372 <p>
1374 </p>
1376 first obtains the topmost commit object name from the remote site
1378 and then tries to obtain the
1380 using the object name of that commit object. Then it reads the
1381 commit object to find out its parent commits and the associate
1382 tree object; it repeats this process until it gets all the
1383 necessary objects. Because of this behavior, they are
1386 transports</em>, because they do not require any git aware smart
1387 server like git Native transport does. Any stock HTTP server
1388 that does not even support directory index would suffice. But
1390 to help dumb transport downloaders.</p></div>
1391 </dd>
1392 </dl></div>
1394 with your current branch.</p></div>
1397 simply do</p></div>
1401 </div></div>
1403 argument.</p></div>
1405 <table><tr>
1408 </td>
1410 keeping as many local repositories as you would like to have
1412 you merge between branches. The advantage of this approach is
1414 out and you may find it easier to switch back and forth if you
1415 juggle multiple lines of development simultaneously. Of
1416 course, you will pay the price of more disk usage to hold
1417 multiple working trees, but disk space is cheap these days.</td>
1418 </tr></table>
1419 </div>
1421 repository from time to time. As a short hand, you can store
1422 the remote repository URL in the local repository's config file
1423 like this:</p></div>
1427 </div></div>
1428 <div class="para"><p>and use the "linus" keyword with <em>git pull</em> instead of the full URL.</p></div>
1431 <li>
1432 <p>
1434 </p>
1435 </li>
1436 <li>
1437 <p>
1439 </p>
1440 </li>
1441 </ol></div>
1444 <li>
1445 <p>
1447 </p>
1448 </li>
1449 <li>
1450 <p>
1452 </p>
1453 </li>
1454 </ol></div>
1455 </div>
1459 with the porcelain that isn't flushing, but we so far did not
1460 talk about how the merge really works. If you are following
1461 this tutorial the first time, I'd suggest to skip to "Publishing
1465 and bring ourselves back to the pre-merge state:</p></div>
1469 ! [master] Merge work in mybranch
1470 * [mybranch] Merge work in mybranch
1471 --
1472 -- [master] Merge work in mybranch
1473 +* [master^2] Some work.
1474 +* [master^] Some fun.</tt></pre>
1475 </div></div>
1476 <div class="para"><p>Remember, before running <em>git merge</em>, our <tt>master</tt> head was at
1481 <pre><tt>$ git checkout mybranch
1482 $ git reset --hard master^2
1483 $ git checkout master
1484 $ git reset --hard master^</tt></pre>
1485 </div></div>
1489 <pre><tt>$ git show-branch
1490 * [master] Some fun.
1491 ! [mybranch] Some work.
1492 --
1493 * [master] Some fun.
1494 + [mybranch] Some work.
1495 *+ [master^] Initial commit</tt></pre>
1496 </div></div>
1499 algorithm. First, it finds the common ancestor between them.
1504 </div></div>
1506 to the standard output, so we captured its output to a variable,
1507 because we will be using it in the next step. By the way, the common
1508 ancestor commit is the "Initial commit" commit in this case. You can
1509 tell it by:</p></div>
1512 <pre><tt>$ git name-rev --name-only --tags $mb
1513 my-first-tag</tt></pre>
1514 </div></div>
1516 this:</p></div>
1520 </div></div>
1522 but it takes three trees, unlike previous examples. This reads
1525 etc.). After reading three trees into three stages, the paths
1527 0. Also paths that are the same in two of three stages are
1530 changed from the common ancestor).</p></div>
1532 trees are left in non-zero stages. At this point, you can
1533 inspect the index file with this command:</p></div>
1536 <pre><tt>$ git ls-files --stage
1541 </div></div>
1544 large projects, when only a small number of files change in one commit,
1546 fairly quickly, leaving only a handful of real changes in non-zero
1547 stages.</p></div>
1551 <pre><tt>$ git ls-files --unmerged
1555 </div></div>
1557 file, using 3-way merge. This is done by giving
1562 <pre><tt>$ git merge-index git-merge-one-file hello
1563 Auto-merging hello
1564 ERROR: Merge conflict in hello
1565 fatal: merge program failed</tt></pre>
1566 </div></div>
1568 describe those three versions, and is responsible to leave the
1569 merge results in the working tree.
1570 It is a fairly straightforward shell script, and
1573 conflicts, and the merge result with conflict marks is left in
1574 the working tree.. This can be seen if you run <tt>ls-files
1578 <pre><tt>$ git ls-files --stage
1583 </div></div>
1589 </div>
1594 it?</p></div>
1598 people to pull from it, but in practice that is not the way
1599 things are usually done. A recommended way is to have a public
1600 repository, make it reachable by other people, and when the
1601 changes you made in your primary working tree are in good shape,
1602 update the public repository from it. This is often called
1605 <table><tr>
1608 </td>
1611 </tr></table>
1612 </div>
1614 your remote (public) repository requires a write privilege on
1615 the remote machine. You need to have an SSH account there to
1618 machine that will house your public repository. This empty
1619 repository will be populated and be kept up-to-date by pushing
1620 into it later. Obviously, this repository creation needs to be
1621 done only once.</p></div>
1623 <table><tr>
1626 </td>
1629 on the remote machine. The communication between the two over
1630 the network internally uses an SSH connection.</td>
1631 </tr></table>
1632 </div>
1634 your public repository is often named after the project name,
1637 an empty directory:</p></div>
1641 </div></div>
1648 </div></div>
1650 changes to be pulled via the transport of your choice. Also
1654 <table><tr>
1657 </td>
1659 shell when you directly run programs; what this means is that if
1663 </tr></table>
1664 </div>
1666 <table><tr>
1669 </td>
1671 you should do <tt>mv my-git.git/hooks/post-update.sample
1672 my-git.git/hooks/post-update</tt> at this point.
1673 This makes sure that every time you push into this
1675 </tr></table>
1676 </div>
1678 Come back to the machine you have your private repository. From
1679 there, run this command:</p></div>
1683 </div></div>
1686 from them in your current repository.</p></div>
1688 repository. Kernel.org mirror network takes care of the
1689 propagation to other publicly visible machines:</p></div>
1693 </div></div>
1694 </div>
1698 is stored for each git object you create. This representation
1699 is efficient to create atomically and safely, but
1700 not so convenient to transport over the network. Since git objects are
1701 immutable once they are created, there is a way to optimize the
1706 </div></div>
1711 directory.</p></div>
1713 <table><tr>
1716 </td>
1719 each other, and if you ever copy them by hand to a different
1720 repository for whatever reason, you should make sure you copy
1721 them together. The former holds all the data from the objects
1722 in the pack, and the latter holds the index for random
1723 access.</td>
1724 </tr></table>
1725 </div>
1727 detect if you have a corrupt pack, but do not worry too much.
1728 Our programs are always perfect ;-).</p></div>
1730 unpacked objects that are contained in the pack file anymore.</p></div>
1734 </div></div>
1738 count-objects</tt> would tell you how many unpacked objects are in
1739 your repository and how much space they are consuming.</p></div>
1741 <table><tr>
1744 </td>
1746 packed repository may contain relatively few objects in a
1747 relatively large pack. If you expect many HTTP pulls from your
1748 public repository you might want to repack & prune often, or
1749 never.</td>
1750 </tr></table>
1751 </div>
1753 "Nothing new to pack.". Once you continue your development and
1755 new pack, that contains objects created since you packed your
1756 repository the last time. We recommend that you pack your project
1757 soon after the initial import (unless you are starting your
1759 while, depending on how active your project is.</p></div>
1760 <div class="para"><p>When a repository is synchronized via <tt>git push</tt> and <tt>git pull</tt>
1761 objects packed in the source repository are usually stored
1762 unpacked in the destination, unless rsync transport is used.
1763 While this allows you to use different packing strategies on
1764 both ends, it also means you may need to repack both
1765 repositories every once in a while.</p></div>
1766 </div>
1770 convenient to organize your project with an informal hierarchy
1771 of developers. Linux kernel development is run this way. There
1773 <a href="http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf">Randy Dunlap's presentation</a>.</p></div>
1774 <div class="para"><p>It should be stressed that this hierarchy is purely <strong>informal</strong>.
1775 There is nothing fundamental in git that enforces the "chain of
1776 patch flow" this hierarchy implies. You do not have to pull
1777 from only one remote repository.</p></div>
1780 <li>
1781 <p>
1782 Prepare your primary repository on your local machine. Your
1783 work is done there.
1784 </p>
1785 </li>
1786 <li>
1787 <p>
1788 Prepare a public repository accessible to others.
1789 </p>
1791 transport protocols (HTTP), you need to keep this repository
1795 but you need to manually enable the hook with
1798 </li>
1799 <li>
1800 <p>
1801 Push into the public repository from your primary
1802 repository.
1803 </p>
1804 </li>
1805 <li>
1806 <p>
1808 pack that contains the initial set of objects as the
1810 used for pulling from your repository supports packed
1811 repositories.
1812 </p>
1813 </li>
1814 <li>
1815 <p>
1816 Keep working in your primary repository. Your changes
1817 include modifications of your own, patches you receive via
1818 e-mails, and merges resulting from pulling the "public"
1819 repositories of your "subsystem maintainers".
1820 </p>
1822 </li>
1823 <li>
1824 <p>
1825 Push your changes to the public repository, and announce it
1826 to the public.
1827 </p>
1828 </li>
1829 <li>
1830 <p>
1832 Go back to step 5. and continue working.
1833 </p>
1834 </li>
1835 </ol></div>
1839 <li>
1840 <p>
1842 repository of the "project lead". The URL used for the
1843 initial cloning is stored in the remote.origin.url
1844 configuration variable.
1845 </p>
1846 </li>
1847 <li>
1848 <p>
1849 Prepare a public repository accessible to others, just like
1850 the "project lead" person does.
1851 </p>
1852 </li>
1853 <li>
1854 <p>
1855 Copy over the packed files from "project lead" public
1856 repository to your public repository, unless the "project
1857 lead" repository lives on the same machine as yours. In the
1859 point at the repository you are borrowing from.
1860 </p>
1861 </li>
1862 <li>
1863 <p>
1864 Push into the public repository from your primary
1866 transport used for pulling from your repository supports
1867 packed repositories.
1868 </p>
1869 </li>
1870 <li>
1871 <p>
1872 Keep working in your primary repository. Your changes
1873 include modifications of your own, patches you receive via
1874 e-mails, and merges resulting from pulling the "public"
1875 repositories of your "project lead" and possibly your
1876 "sub-subsystem maintainers".
1877 </p>
1879 like.</p></div>
1880 </li>
1881 <li>
1882 <p>
1883 Push your changes to your public repository, and ask your
1885 maintainers" to pull from it.
1886 </p>
1887 </li>
1888 <li>
1889 <p>
1891 Go back to step 5. and continue working.
1892 </p>
1893 </li>
1894 </ol></div>
1896 not have a "public" repository is somewhat different. It goes
1897 like this:</p></div>
1899 <li>
1900 <p>
1903 maintainer", if you work on a subsystem). The URL used for
1904 the initial cloning is stored in the remote.origin.url
1905 configuration variable.
1906 </p>
1907 </li>
1908 <li>
1909 <p>
1911 </p>
1912 </li>
1913 <li>
1914 <p>
1916 upstream every once in a while. This does only the first
1919 </p>
1920 </li>
1921 <li>
1922 <p>
1925 unmerged changes forward to the updated upstream.
1926 </p>
1927 </li>
1928 <li>
1929 <p>
1931 submission to your upstream and send it out. Go back to
1932 step 2. and continue.
1933 </p>
1934 </li>
1935 </ol></div>
1936 </div>
1937 <h2 id="_working_with_others_shared_repository_style">Working with Others, Shared Repository Style</h2>
1940 suggested in the previous section may be new to you. You do not
1941 have to worry. git supports "shared public repository" style of
1942 cooperation you are probably more familiar with as well.</p></div>
1943 <div class="para"><p>See <a href="gitcvs-migration.html">gitcvs-migration(7)</a> for the details.</p></div>
1944 </div>
1948 a time. It is easy to manage those more-or-less independent tasks
1949 using branches with git.</p></div>
1951 with "fun and work" example using two branches. The idea is the
1952 same if there are more than two branches. Let's say you started
1954 branch, and two independent fixes in the "commit-fix" and
1958 <pre><tt>$ git show-branch
1959 ! [commit-fix] Fix commit message normalization.
1960 ! [diff-fix] Fix rename detection.
1961 * [master] Release candidate #1
1962 ---
1963 + [diff-fix] Fix rename detection.
1964 + [diff-fix~1] Better common substring algorithm.
1965 + [commit-fix] Fix commit message normalization.
1966 * [master] Release candidate #1
1968 </div></div>
1976 </div></div>
1980 <pre><tt>$ git show-branch
1981 ! [commit-fix] Fix commit message normalization.
1982 ! [diff-fix] Fix rename detection.
1983 * [master] Merge fix in commit-fix
1984 ---
1985 - [master] Merge fix in commit-fix
1986 + * [commit-fix] Fix commit message normalization.
1987 - [master~1] Merge fix in diff-fix
1988 +* [diff-fix] Fix rename detection.
1989 +* [diff-fix~1] Better common substring algorithm.
1992 </div></div>
1994 first and the other next, when what you have are a set of truly
1995 independent changes (if the order mattered, then they are not
1996 independent by definition). You could instead merge those two
1997 branches into the current branch at once. First let's undo what
1998 we just did and start over. We would want to get the master
2003 </div></div>
2010 <pre><tt>$ git merge commit-fix diff-fix
2011 $ git show-branch
2012 ! [commit-fix] Fix commit message normalization.
2013 ! [diff-fix] Fix rename detection.
2014 * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
2015 ---
2016 - [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
2017 + * [commit-fix] Fix commit message normalization.
2018 +* [diff-fix] Fix rename detection.
2019 +* [diff-fix~1] Better common substring algorithm.
2022 </div></div>
2024 is a valid thing to do and often makes it easier to view the
2025 commit history if you are merging more than two independent
2026 changes at the same time. However, if you have merge conflicts
2027 with any of the branches you are merging in and need to hand
2028 resolve, that is an indication that the development happened in
2029 those branches were not independent after all, and you should
2030 merge two at a time, documenting how you resolved the conflicts,
2031 and the reason why you preferred changes made in one side over
2032 the other. Otherwise it would make the project history harder
2033 to follow, not easier.</p></div>
2034 </div>
2043 </div>
2047 </div>
2051 </div>
2052 </div>
2053 </body>
2054 </html>