| blob | 2ea2db98d121cf80de1de9fdca13ee93dde0d4fc |
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>
418 </div>
422 changes to it, and share changes with other developers.</p></div>
423 <div class="paragraph"><p>If you are instead primarily interested in using git to fetch a project,
424 for example, to test the latest version, you may prefer to start with
431 </div></div>
436 </div></div>
440 public email address before doing any operation. The easiest
441 way to do so is:</p></div>
445 $ git config --global user.email you@yourdomain.example.com</tt></pre>
446 </div></div>
447 </div>
451 can place it under git revision control as follows.</p></div>
454 <pre><tt>$ tar xzf project.tar.gz
455 $ cd project
456 $ git init</tt></pre>
457 </div></div>
462 </div></div>
463 <div class="paragraph"><p>You’ve now initialized the working directory—you may notice a new
465 <div class="paragraph"><p>Next, tell git to take a snapshot of the contents of all files under the
470 </div></div>
471 <div class="paragraph"><p>This snapshot is now stored in a temporary staging area which git calls
472 the "index". You can permanently store the contents of the index in the
477 </div></div>
478 <div class="paragraph"><p>This will prompt you for a commit message. You’ve now stored the first
479 version of your project in git.</p></div>
480 </div>
483 <div class="paragraph"><p>Modify some files, then add their updated contents to the index:</p></div>
487 </div></div>
488 <div class="paragraph"><p>You are now ready to commit. You can see what is about to be committed
493 </div></div>
495 you’ve made but not yet added to the index.) You can also get a brief
499 <pre><tt>$ git status
500 # On branch master
501 # Changes to be committed:
502 # (use "git reset HEAD <file>..." to unstage)
503 #
504 # modified: file1
505 # modified: file2
506 # modified: file3
507 #</tt></pre>
508 </div></div>
509 <div class="paragraph"><p>If you need to make any further adjustments, do so now, and then add any
510 newly modified content to the index. Finally, commit your changes with:</p></div>
514 </div></div>
515 <div class="paragraph"><p>This will again prompt you for a message describing the change, and then
516 record a new version of the project.</p></div>
517 <div class="paragraph"><p>Alternatively, instead of running <em>git add</em> beforehand, you can use</p></div>
521 </div></div>
523 them to the index, and commit, all in one step.</p></div>
524 <div class="paragraph"><p>A note on commit messages: Though not required, it’s a good idea to
525 begin the commit message with a single short (less than 50 character)
526 line summarizing the change, followed by a blank line and then a more
527 thorough description. Tools that turn commits into email, for
528 example, use the first line on the Subject: line and the rest of the
529 commit in the body.</p></div>
530 </div>
533 <div class="paragraph"><p>Many revision control systems provide an <tt>add</tt> command that tells the
536 and newly modified files, and in both cases it takes a snapshot of the
537 given files and stages that content in the index, ready for inclusion in
538 the next commit.</p></div>
539 </div>
546 </div></div>
551 </div></div>
553 each step</p></div>
557 </div></div>
558 </div>
566 </div></div>
571 </div></div>
575 <pre><tt> experimental
576 * master</tt></pre>
577 </div></div>
579 "master" branch is a default branch that was created for you
580 automatically. The asterisk marks the branch you are currently on;
581 type</p></div>
585 </div></div>
587 change, and switch back to the master branch:</p></div>
590 <pre><tt>(edit file)
591 $ git commit -a
592 $ git checkout master</tt></pre>
593 </div></div>
599 <pre><tt>(edit file)
600 $ git commit -a</tt></pre>
601 </div></div>
603 made in each. To merge the changes made in experimental into master, run</p></div>
607 </div></div>
608 <div class="paragraph"><p>If the changes don’t conflict, you’re done. If there are conflicts,
609 markers will be left in the problematic files showing the conflict;</p></div>
613 </div></div>
615 conflicts,</p></div>
619 </div></div>
624 </div></div>
625 <div class="paragraph"><p>will show a nice graphical representation of the resulting history.</p></div>
630 </div></div>
632 already in the current branch.</p></div>
634 delete the branch with</p></div>
638 </div></div>
640 out.</p></div>
641 </div>
645 /home/alice/project, and that Bob, who has a home directory on the
646 same machine, wants to contribute.</p></div>
651 </div></div>
652 <div class="paragraph"><p>This creates a new directory "myrepo" containing a clone of Alice’s
653 repository. The clone is on an equal footing with the original
658 <pre><tt>(edit files)
659 bob$ git commit -a
660 (repeat as necessary)</tt></pre>
661 </div></div>
662 <div class="paragraph"><p>When he’s ready, he tells Alice to pull changes from the repository
663 at /home/bob/myrepo. She does this with:</p></div>
666 <pre><tt>alice$ cd /home/alice/project
667 alice$ git pull /home/bob/myrepo master</tt></pre>
668 </div></div>
669 <div class="paragraph"><p>This merges the changes from Bob’s "master" branch into Alice’s
670 current branch. If Alice has made her own changes in the meantime,
671 then she may need to manually fix any conflicts.</p></div>
673 from a remote branch, then merges them into the current branch.</p></div>
674 <div class="paragraph"><p>Note that in general, Alice would want her local changes committed before
676 their histories forked, Alice will use her working tree and the index to
677 resolve conflicts, and existing local changes will interfere with the
678 conflict resolution process (git will still perform the fetch but will
679 refuse to merge --- Alice will have to get rid of her local changes in
680 some way and pull again when this happens).</p></div>
681 <div class="paragraph"><p>Alice can peek at what Bob did without merging first, using the "fetch"
682 command; this allows Alice to inspect what Bob did, using a special
683 symbol "FETCH_HEAD", in order to determine if he has anything worth
684 pulling, like this:</p></div>
687 <pre><tt>alice$ git fetch /home/bob/myrepo master
688 alice$ git log -p HEAD..FETCH_HEAD</tt></pre>
689 </div></div>
692 from the FETCH_HEAD but exclude anything that is reachable from HEAD".
693 Alice already knows everything that leads to her current state (HEAD),
694 and reviews what Bob has in his state (FETCH_HEAD) that she has not
695 seen with this command.</p></div>
697 she can issue the following command:</p></div>
701 </div></div>
702 <div class="paragraph"><p>This uses the same two-dot range notation we saw earlier with <em>git log</em>.</p></div>
704 She can use three-dot form instead of the two-dot form:</p></div>
708 </div></div>
714 decide to continue working without pulling from Bob. If Bob’s history
715 does have something Alice would immediately need, Alice may choose to
716 stash her work-in-progress first, do a "pull", and then finally unstash
717 her work-in-progress on top of the resulting history.</p></div>
719 unusual to interact with the same repository over and over
721 it easier:</p></div>
725 </div></div>
728 branch, using:</p></div>
732 </div></div>
735 fetched is stored in a remote-tracking branch, in this case
740 </div></div>
744 could merge the changes into her master branch:</p></div>
748 </div></div>
749 <div class="paragraph"><p>This <tt>merge</tt> can also be done by <em>pulling from her own remote-tracking
754 </div></div>
756 regardless of what else is given on the command line.</p></div>
757 <div class="paragraph"><p>Later, Bob can update his repo with Alice’s latest changes using</p></div>
761 </div></div>
762 <div class="paragraph"><p>Note that he doesn’t need to give the path to Alice’s repository;
763 when Bob cloned Alice’s repository, git stored the location of her
764 repository in the repository configuration, and that location is
765 used for pulls:</p></div>
768 <pre><tt>bob$ git config --get remote.origin.url
769 /home/alice/project</tt></pre>
770 </div></div>
771 <div class="paragraph"><p>(The complete configuration created by <em>git clone</em> is visible using
773 explains the meaning of each option.)</p></div>
774 <div class="paragraph"><p>Git also keeps a pristine copy of Alice’s master branch under the
778 <pre><tt>bob$ git branch -r
779 origin/master</tt></pre>
780 </div></div>
782 perform clones and pulls using the ssh protocol:</p></div>
786 </div></div>
792 </div>
797 Note that first line of each git log entry also gives a name for the
798 commit:</p></div>
801 <pre><tt>$ git log
802 commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
806 merge-base: Clarify the comments on post processing.</tt></pre>
807 </div></div>
808 <div class="paragraph"><p>We can give this name to <em>git show</em> to see the details about this
809 commit.</p></div>
813 </div></div>
815 part of the name that is long enough to uniquely identify the commit:</p></div>
818 <pre><tt>$ git show c82a22c39c # the first few characters of the name are
819 # usually enough
820 $ git show HEAD # the tip of the current branch
822 </div></div>
824 which points to the previous state of the project:</p></div>
827 <pre><tt>$ git show HEAD^ # to see the parent of HEAD
828 $ git show HEAD^^ # to see the grandparent of HEAD
830 </div></div>
836 </div></div>
841 </div></div>
843 share this name with other people (for example, to identify a release
844 version), you should create a "tag" object, and perhaps sign it; see
847 names. For example:</p></div>
850 <pre><tt>$ git diff v2.5 HEAD # compare the current HEAD to v2.5
851 $ git branch stable v2.5 # start a new branch named "stable" based
852 # at v2.5
853 $ git reset --hard HEAD^ # reset your current branch and working
854 # directory to its state at HEAD^</tt></pre>
855 </div></div>
857 in the working directory, it will also remove all later commits from
858 this branch. If this branch is the only branch containing those
860 publicly-visible branch that other developers pull from, as it will
861 force needless merges on other developers to clean up the history.
863 instead.</p></div>
864 <div class="paragraph"><p>The <em>git grep</em> command can search for strings in any version of your
865 project, so</p></div>
869 </div></div>
871 <div class="paragraph"><p>If you leave out the commit name, <em>git grep</em> will search any of the
872 files it manages in your current directory. So</p></div>
876 </div></div>
877 <div class="paragraph"><p>is a quick way to search just the files that are tracked by git.</p></div>
882 <pre><tt>$ git log v2.5..v2.6 # commits between v2.5 and v2.6
883 $ git log v2.5.. # commits since v2.5
885 $ git log v2.5.. Makefile # commits since v2.5 which modify
886 # Makefile</tt></pre>
887 </div></div>
888 <div class="paragraph"><p>You can also give <em>git log</em> a "range" of commits where the first is not
889 necessarily an ancestor of the second; for example, if the tips of
891 commit some time ago, then</p></div>
895 </div></div>
897 stable branch, while</p></div>
901 </div></div>
903 the master branch.</p></div>
904 <div class="paragraph"><p>The <em>git log</em> command has a weakness: it must present commits in a
905 list. When the history has lines of development that diverged and
907 those commits is meaningless.</p></div>
910 visualizing their history. For example,</p></div>
914 </div></div>
916 that modified files under the "drivers" directory. (Note: you can
917 adjust gitk’s fonts by holding down the control key while pressing
920 to precede any filename by a commit, to specify a particular version
921 of the file:</p></div>
925 </div></div>
930 </div></div>
931 </div>
935 control for your projects. However, to fully understand the depth
936 and power of git you need to understand two simple ideas on which it
937 is based:</p></div>
939 <li>
940 <p>
941 The object database is the rather elegant system used to
942 store the history of your project—files, directories, and
943 commits.
944 </p>
945 </li>
946 <li>
947 <p>
948 The index file is a cache of the state of a directory tree,
949 used to create commits, check out working directories, and
950 hold the various trees involved in a merge.
951 </p>
952 </li>
953 </ul></div>
955 database, the index file, and a few other odds and ends that you’ll
956 need to make the most of git. You can find it at <a href="gittutorial-2.html">gittutorial-2(7)</a>.</p></div>
958 digressions that may be interesting at this point are:</p></div>
960 <li>
961 <p>
962 <a href="git-format-patch.html">git-format-patch(1)</a>, <a href="git-am.html">git-am(1)</a>: These convert
963 series of git commits into emailed patches, and vice versa,
964 useful for projects such as the Linux kernel which rely heavily
965 on emailed patches.
966 </p>
967 </li>
968 <li>
969 <p>
971 project, one way to track down the bug is by searching through
972 the history to find the exact commit that’s to blame. Git bisect
973 can help you perform a binary search for that commit. It is
974 smart enough to perform a close-to-optimal search even in the
975 case of complex non-linear history with lots of merged branches.
976 </p>
977 </li>
978 <li>
979 <p>
981 workflows.
982 </p>
983 </li>
984 <li>
985 <p>
987 </p>
988 </li>
989 <li>
990 <p>
992 </p>
993 </li>
994 </ul></div>
995 </div>
1006 </div>
1010 </div>
1014 </div>
1015 </div>
1016 </body>
1017 </html>