| blob | 26e9d619ffc3a3db7137ccd0def316c2d875c2a2 |
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 gittutorial(7) Manual Page
407 </h1>
410 <p>gittutorial -
411 A tutorial introduction to git (for version 1.5.1 or newer)
412 </p>
413 </div>
414 </div>
420 </div></div>
421 </div>
425 changes to it, and share changes with other developers.</p></div>
426 <div class="paragraph"><p>If you are instead primarily interested in using git to fetch a project,
427 for example, to test the latest version, you may prefer to start with
434 </div></div>
439 </div></div>
443 public email address before doing any operation. The easiest
444 way to do so is:</p></div>
448 $ git config --global user.email you@yourdomain.example.com</tt></pre>
449 </div></div>
450 </div>
454 can place it under git revision control as follows.</p></div>
457 <pre><tt>$ tar xzf project.tar.gz
458 $ cd project
459 $ git init</tt></pre>
460 </div></div>
465 </div></div>
466 <div class="paragraph"><p>You’ve now initialized the working directory—you may notice a new
468 <div class="paragraph"><p>Next, tell git to take a snapshot of the contents of all files under the
473 </div></div>
474 <div class="paragraph"><p>This snapshot is now stored in a temporary staging area which git calls
475 the "index". You can permanently store the contents of the index in the
480 </div></div>
481 <div class="paragraph"><p>This will prompt you for a commit message. You’ve now stored the first
482 version of your project in git.</p></div>
483 </div>
486 <div class="paragraph"><p>Modify some files, then add their updated contents to the index:</p></div>
490 </div></div>
491 <div class="paragraph"><p>You are now ready to commit. You can see what is about to be committed
496 </div></div>
498 you’ve made but not yet added to the index.) You can also get a brief
502 <pre><tt>$ git status
503 # On branch master
504 # Changes to be committed:
505 # (use "git reset HEAD <file>..." to unstage)
506 #
507 # modified: file1
508 # modified: file2
509 # modified: file3
510 #</tt></pre>
511 </div></div>
512 <div class="paragraph"><p>If you need to make any further adjustments, do so now, and then add any
513 newly modified content to the index. Finally, commit your changes with:</p></div>
517 </div></div>
518 <div class="paragraph"><p>This will again prompt you for a message describing the change, and then
519 record a new version of the project.</p></div>
520 <div class="paragraph"><p>Alternatively, instead of running <em>git add</em> beforehand, you can use</p></div>
524 </div></div>
526 them to the index, and commit, all in one step.</p></div>
527 <div class="paragraph"><p>A note on commit messages: Though not required, it’s a good idea to
528 begin the commit message with a single short (less than 50 character)
529 line summarizing the change, followed by a blank line and then a more
530 thorough description. Tools that turn commits into email, for
531 example, use the first line on the Subject: line and the rest of the
532 commit in the body.</p></div>
533 </div>
536 <div class="paragraph"><p>Many revision control systems provide an <tt>add</tt> command that tells the
539 and newly modified files, and in both cases it takes a snapshot of the
540 given files and stages that content in the index, ready for inclusion in
541 the next commit.</p></div>
542 </div>
549 </div></div>
554 </div></div>
556 each step</p></div>
560 </div></div>
561 </div>
569 </div></div>
574 </div></div>
578 <pre><tt> experimental
579 * master</tt></pre>
580 </div></div>
582 "master" branch is a default branch that was created for you
583 automatically. The asterisk marks the branch you are currently on;
584 type</p></div>
588 </div></div>
590 change, and switch back to the master branch:</p></div>
593 <pre><tt>(edit file)
594 $ git commit -a
595 $ git checkout master</tt></pre>
596 </div></div>
602 <pre><tt>(edit file)
603 $ git commit -a</tt></pre>
604 </div></div>
606 made in each. To merge the changes made in experimental into master, run</p></div>
610 </div></div>
611 <div class="paragraph"><p>If the changes don’t conflict, you’re done. If there are conflicts,
612 markers will be left in the problematic files showing the conflict;</p></div>
616 </div></div>
618 conflicts,</p></div>
622 </div></div>
627 </div></div>
628 <div class="paragraph"><p>will show a nice graphical representation of the resulting history.</p></div>
633 </div></div>
635 already in the current branch.</p></div>
637 delete the branch with</p></div>
641 </div></div>
643 out.</p></div>
644 </div>
648 /home/alice/project, and that Bob, who has a home directory on the
649 same machine, wants to contribute.</p></div>
654 </div></div>
655 <div class="paragraph"><p>This creates a new directory "myrepo" containing a clone of Alice’s
656 repository. The clone is on an equal footing with the original
661 <pre><tt>(edit files)
662 bob$ git commit -a
663 (repeat as necessary)</tt></pre>
664 </div></div>
665 <div class="paragraph"><p>When he’s ready, he tells Alice to pull changes from the repository
666 at /home/bob/myrepo. She does this with:</p></div>
669 <pre><tt>alice$ cd /home/alice/project
670 alice$ git pull /home/bob/myrepo master</tt></pre>
671 </div></div>
672 <div class="paragraph"><p>This merges the changes from Bob’s "master" branch into Alice’s
673 current branch. If Alice has made her own changes in the meantime,
674 then she may need to manually fix any conflicts.</p></div>
676 from a remote branch, then merges them into the current branch.</p></div>
677 <div class="paragraph"><p>Note that in general, Alice would want her local changes committed before
679 their histories forked, Alice will use her working tree and the index to
680 resolve conflicts, and existing local changes will interfere with the
681 conflict resolution process (git will still perform the fetch but will
682 refuse to merge --- Alice will have to get rid of her local changes in
683 some way and pull again when this happens).</p></div>
684 <div class="paragraph"><p>Alice can peek at what Bob did without merging first, using the "fetch"
685 command; this allows Alice to inspect what Bob did, using a special
686 symbol "FETCH_HEAD", in order to determine if he has anything worth
687 pulling, like this:</p></div>
690 <pre><tt>alice$ git fetch /home/bob/myrepo master
691 alice$ git log -p HEAD..FETCH_HEAD</tt></pre>
692 </div></div>
695 from the FETCH_HEAD but exclude anything that is reachable from HEAD".
696 Alice already knows everything that leads to her current state (HEAD),
697 and reviews what Bob has in his state (FETCH_HEAD) that she has not
698 seen with this command.</p></div>
700 she can issue the following command:</p></div>
704 </div></div>
705 <div class="paragraph"><p>This uses the same two-dot range notation we saw earlier with <em>git log</em>.</p></div>
707 She can use three-dot form instead of the two-dot form:</p></div>
711 </div></div>
717 decide to continue working without pulling from Bob. If Bob’s history
718 does have something Alice would immediately need, Alice may choose to
719 stash her work-in-progress first, do a "pull", and then finally unstash
720 her work-in-progress on top of the resulting history.</p></div>
722 unusual to interact with the same repository over and over
724 it easier:</p></div>
728 </div></div>
731 branch, using:</p></div>
735 </div></div>
738 fetched is stored in a remote-tracking branch, in this case
743 </div></div>
747 could merge the changes into her master branch:</p></div>
751 </div></div>
752 <div class="paragraph"><p>This <tt>merge</tt> can also be done by <em>pulling from her own remote-tracking
757 </div></div>
759 regardless of what else is given on the command line.</p></div>
760 <div class="paragraph"><p>Later, Bob can update his repo with Alice’s latest changes using</p></div>
764 </div></div>
765 <div class="paragraph"><p>Note that he doesn’t need to give the path to Alice’s repository;
766 when Bob cloned Alice’s repository, git stored the location of her
767 repository in the repository configuration, and that location is
768 used for pulls:</p></div>
771 <pre><tt>bob$ git config --get remote.origin.url
772 /home/alice/project</tt></pre>
773 </div></div>
774 <div class="paragraph"><p>(The complete configuration created by <em>git clone</em> is visible using
776 explains the meaning of each option.)</p></div>
777 <div class="paragraph"><p>Git also keeps a pristine copy of Alice’s master branch under the
781 <pre><tt>bob$ git branch -r
782 origin/master</tt></pre>
783 </div></div>
785 perform clones and pulls using the ssh protocol:</p></div>
789 </div></div>
795 </div>
800 Note that first line of each git log entry also gives a name for the
801 commit:</p></div>
804 <pre><tt>$ git log
805 commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
809 merge-base: Clarify the comments on post processing.</tt></pre>
810 </div></div>
811 <div class="paragraph"><p>We can give this name to <em>git show</em> to see the details about this
812 commit.</p></div>
816 </div></div>
818 part of the name that is long enough to uniquely identify the commit:</p></div>
821 <pre><tt>$ git show c82a22c39c # the first few characters of the name are
822 # usually enough
823 $ git show HEAD # the tip of the current branch
825 </div></div>
827 which points to the previous state of the project:</p></div>
830 <pre><tt>$ git show HEAD^ # to see the parent of HEAD
831 $ git show HEAD^^ # to see the grandparent of HEAD
833 </div></div>
839 </div></div>
844 </div></div>
846 share this name with other people (for example, to identify a release
847 version), you should create a "tag" object, and perhaps sign it; see
850 names. For example:</p></div>
853 <pre><tt>$ git diff v2.5 HEAD # compare the current HEAD to v2.5
854 $ git branch stable v2.5 # start a new branch named "stable" based
855 # at v2.5
856 $ git reset --hard HEAD^ # reset your current branch and working
857 # directory to its state at HEAD^</tt></pre>
858 </div></div>
860 in the working directory, it will also remove all later commits from
861 this branch. If this branch is the only branch containing those
863 publicly-visible branch that other developers pull from, as it will
864 force needless merges on other developers to clean up the history.
866 instead.</p></div>
867 <div class="paragraph"><p>The <em>git grep</em> command can search for strings in any version of your
868 project, so</p></div>
872 </div></div>
874 <div class="paragraph"><p>If you leave out the commit name, <em>git grep</em> will search any of the
875 files it manages in your current directory. So</p></div>
879 </div></div>
880 <div class="paragraph"><p>is a quick way to search just the files that are tracked by git.</p></div>
885 <pre><tt>$ git log v2.5..v2.6 # commits between v2.5 and v2.6
886 $ git log v2.5.. # commits since v2.5
888 $ git log v2.5.. Makefile # commits since v2.5 which modify
889 # Makefile</tt></pre>
890 </div></div>
891 <div class="paragraph"><p>You can also give <em>git log</em> a "range" of commits where the first is not
892 necessarily an ancestor of the second; for example, if the tips of
894 commit some time ago, then</p></div>
898 </div></div>
900 stable branch, while</p></div>
904 </div></div>
906 the master branch.</p></div>
907 <div class="paragraph"><p>The <em>git log</em> command has a weakness: it must present commits in a
908 list. When the history has lines of development that diverged and
910 those commits is meaningless.</p></div>
913 visualizing their history. For example,</p></div>
917 </div></div>
919 that modified files under the "drivers" directory. (Note: you can
920 adjust gitk’s fonts by holding down the control key while pressing
923 to precede any filename by a commit, to specify a particular version
924 of the file:</p></div>
928 </div></div>
933 </div></div>
934 </div>
938 control for your projects. However, to fully understand the depth
939 and power of git you need to understand two simple ideas on which it
940 is based:</p></div>
942 <li>
943 <p>
944 The object database is the rather elegant system used to
945 store the history of your project—files, directories, and
946 commits.
947 </p>
948 </li>
949 <li>
950 <p>
951 The index file is a cache of the state of a directory tree,
952 used to create commits, check out working directories, and
953 hold the various trees involved in a merge.
954 </p>
955 </li>
956 </ul></div>
958 database, the index file, and a few other odds and ends that you’ll
959 need to make the most of git. You can find it at <a href="gittutorial-2.html">gittutorial-2(7)</a>.</p></div>
961 digressions that may be interesting at this point are:</p></div>
963 <li>
964 <p>
965 <a href="git-format-patch.html">git-format-patch(1)</a>, <a href="git-am.html">git-am(1)</a>: These convert
966 series of git commits into emailed patches, and vice versa,
967 useful for projects such as the Linux kernel which rely heavily
968 on emailed patches.
969 </p>
970 </li>
971 <li>
972 <p>
974 project, one way to track down the bug is by searching through
975 the history to find the exact commit that’s to blame. Git bisect
976 can help you perform a binary search for that commit. It is
977 smart enough to perform a close-to-optimal search even in the
978 case of complex non-linear history with lots of merged branches.
979 </p>
980 </li>
981 <li>
982 <p>
984 workflows.
985 </p>
986 </li>
987 <li>
988 <p>
990 </p>
991 </li>
992 <li>
993 <p>
995 </p>
996 </li>
997 </ul></div>
998 </div>
1009 </div>
1013 </div>
1017 </div>
1018 </div>
1019 </body>
1020 </html>