textconv: support for cat_file
[git/dscho.git] / Documentation / gittutorial.txt
blob1c1606696e3771f1b881c18689b049b53a8a3539
1 gittutorial(7)
2 ==============
4 NAME
5 ----
6 gittutorial - A tutorial introduction to git (for version 1.5.1 or newer)
8 SYNOPSIS
9 --------
10 git *
12 DESCRIPTION
13 -----------
15 This tutorial explains how to import a new project into git, make
16 changes to it, and share changes with other developers.
18 If you are instead primarily interested in using git to fetch a project,
19 for example, to test the latest version, you may prefer to start with
20 the first two chapters of link:user-manual.html[The Git User's Manual].
22 First, note that you can get documentation for a command such as
23 `git log --graph` with:
25 ------------------------------------------------
26 $ man git-log
27 ------------------------------------------------
29 or:
31 ------------------------------------------------
32 $ git help log
33 ------------------------------------------------
35 With the latter, you can use the manual viewer of your choice; see
36 linkgit:git-help[1] for more information.
38 It is a good idea to introduce yourself to git with your name and
39 public email address before doing any operation.  The easiest
40 way to do so is:
42 ------------------------------------------------
43 $ git config --global user.name "Your Name Comes Here"
44 $ git config --global user.email you@yourdomain.example.com
45 ------------------------------------------------
48 Importing a new project
49 -----------------------
51 Assume you have a tarball project.tar.gz with your initial work.  You
52 can place it under git revision control as follows.
54 ------------------------------------------------
55 $ tar xzf project.tar.gz
56 $ cd project
57 $ git init
58 ------------------------------------------------
60 Git will reply
62 ------------------------------------------------
63 Initialized empty Git repository in .git/
64 ------------------------------------------------
66 You've now initialized the working directory--you may notice a new
67 directory created, named ".git".
69 Next, tell git to take a snapshot of the contents of all files under the
70 current directory (note the '.'), with 'git add':
72 ------------------------------------------------
73 $ git add .
74 ------------------------------------------------
76 This snapshot is now stored in a temporary staging area which git calls
77 the "index".  You can permanently store the contents of the index in the
78 repository with 'git commit':
80 ------------------------------------------------
81 $ git commit
82 ------------------------------------------------
84 This will prompt you for a commit message.  You've now stored the first
85 version of your project in git.
87 Making changes
88 --------------
90 Modify some files, then add their updated contents to the index:
92 ------------------------------------------------
93 $ git add file1 file2 file3
94 ------------------------------------------------
96 You are now ready to commit.  You can see what is about to be committed
97 using 'git diff' with the --cached option:
99 ------------------------------------------------
100 $ git diff --cached
101 ------------------------------------------------
103 (Without --cached, 'git diff' will show you any changes that
104 you've made but not yet added to the index.)  You can also get a brief
105 summary of the situation with 'git status':
107 ------------------------------------------------
108 $ git status
109 # On branch master
110 # Changes to be committed:
111 #   (use "git reset HEAD <file>..." to unstage)
113 #       modified:   file1
114 #       modified:   file2
115 #       modified:   file3
117 ------------------------------------------------
119 If you need to make any further adjustments, do so now, and then add any
120 newly modified content to the index.  Finally, commit your changes with:
122 ------------------------------------------------
123 $ git commit
124 ------------------------------------------------
126 This will again prompt you for a message describing the change, and then
127 record a new version of the project.
129 Alternatively, instead of running 'git add' beforehand, you can use
131 ------------------------------------------------
132 $ git commit -a
133 ------------------------------------------------
135 which will automatically notice any modified (but not new) files, add
136 them to the index, and commit, all in one step.
138 A note on commit messages: Though not required, it's a good idea to
139 begin the commit message with a single short (less than 50 character)
140 line summarizing the change, followed by a blank line and then a more
141 thorough description.  Tools that turn commits into email, for
142 example, use the first line on the Subject: line and the rest of the
143 commit in the body.
145 Git tracks content not files
146 ----------------------------
148 Many revision control systems provide an `add` command that tells the
149 system to start tracking changes to a new file.  Git's `add` command
150 does something simpler and more powerful: 'git add' is used both for new
151 and newly modified files, and in both cases it takes a snapshot of the
152 given files and stages that content in the index, ready for inclusion in
153 the next commit.
155 Viewing project history
156 -----------------------
158 At any point you can view the history of your changes using
160 ------------------------------------------------
161 $ git log
162 ------------------------------------------------
164 If you also want to see complete diffs at each step, use
166 ------------------------------------------------
167 $ git log -p
168 ------------------------------------------------
170 Often the overview of the change is useful to get a feel of
171 each step
173 ------------------------------------------------
174 $ git log --stat --summary
175 ------------------------------------------------
177 Managing branches
178 -----------------
180 A single git repository can maintain multiple branches of
181 development.  To create a new branch named "experimental", use
183 ------------------------------------------------
184 $ git branch experimental
185 ------------------------------------------------
187 If you now run
189 ------------------------------------------------
190 $ git branch
191 ------------------------------------------------
193 you'll get a list of all existing branches:
195 ------------------------------------------------
196   experimental
197 * master
198 ------------------------------------------------
200 The "experimental" branch is the one you just created, and the
201 "master" branch is a default branch that was created for you
202 automatically.  The asterisk marks the branch you are currently on;
203 type
205 ------------------------------------------------
206 $ git checkout experimental
207 ------------------------------------------------
209 to switch to the experimental branch.  Now edit a file, commit the
210 change, and switch back to the master branch:
212 ------------------------------------------------
213 (edit file)
214 $ git commit -a
215 $ git checkout master
216 ------------------------------------------------
218 Check that the change you made is no longer visible, since it was
219 made on the experimental branch and you're back on the master branch.
221 You can make a different change on the master branch:
223 ------------------------------------------------
224 (edit file)
225 $ git commit -a
226 ------------------------------------------------
228 at this point the two branches have diverged, with different changes
229 made in each.  To merge the changes made in experimental into master, run
231 ------------------------------------------------
232 $ git merge experimental
233 ------------------------------------------------
235 If the changes don't conflict, you're done.  If there are conflicts,
236 markers will be left in the problematic files showing the conflict;
238 ------------------------------------------------
239 $ git diff
240 ------------------------------------------------
242 will show this.  Once you've edited the files to resolve the
243 conflicts,
245 ------------------------------------------------
246 $ git commit -a
247 ------------------------------------------------
249 will commit the result of the merge. Finally,
251 ------------------------------------------------
252 $ gitk
253 ------------------------------------------------
255 will show a nice graphical representation of the resulting history.
257 At this point you could delete the experimental branch with
259 ------------------------------------------------
260 $ git branch -d experimental
261 ------------------------------------------------
263 This command ensures that the changes in the experimental branch are
264 already in the current branch.
266 If you develop on a branch crazy-idea, then regret it, you can always
267 delete the branch with
269 -------------------------------------
270 $ git branch -D crazy-idea
271 -------------------------------------
273 Branches are cheap and easy, so this is a good way to try something
274 out.
276 Using git for collaboration
277 ---------------------------
279 Suppose that Alice has started a new project with a git repository in
280 /home/alice/project, and that Bob, who has a home directory on the
281 same machine, wants to contribute.
283 Bob begins with:
285 ------------------------------------------------
286 bob$ git clone /home/alice/project myrepo
287 ------------------------------------------------
289 This creates a new directory "myrepo" containing a clone of Alice's
290 repository.  The clone is on an equal footing with the original
291 project, possessing its own copy of the original project's history.
293 Bob then makes some changes and commits them:
295 ------------------------------------------------
296 (edit files)
297 bob$ git commit -a
298 (repeat as necessary)
299 ------------------------------------------------
301 When he's ready, he tells Alice to pull changes from the repository
302 at /home/bob/myrepo.  She does this with:
304 ------------------------------------------------
305 alice$ cd /home/alice/project
306 alice$ git pull /home/bob/myrepo master
307 ------------------------------------------------
309 This merges the changes from Bob's "master" branch into Alice's
310 current branch.  If Alice has made her own changes in the meantime,
311 then she may need to manually fix any conflicts.
313 The "pull" command thus performs two operations: it fetches changes
314 from a remote branch, then merges them into the current branch.
316 Note that in general, Alice would want her local changes committed before
317 initiating this "pull".  If Bob's work conflicts with what Alice did since
318 their histories forked, Alice will use her working tree and the index to
319 resolve conflicts, and existing local changes will interfere with the
320 conflict resolution process (git will still perform the fetch but will
321 refuse to merge --- Alice will have to get rid of her local changes in
322 some way and pull again when this happens).
324 Alice can peek at what Bob did without merging first, using the "fetch"
325 command; this allows Alice to inspect what Bob did, using a special
326 symbol "FETCH_HEAD", in order to determine if he has anything worth
327 pulling, like this:
329 ------------------------------------------------
330 alice$ git fetch /home/bob/myrepo master
331 alice$ git log -p HEAD..FETCH_HEAD
332 ------------------------------------------------
334 This operation is safe even if Alice has uncommitted local changes.
335 The range notation "HEAD..FETCH_HEAD" means "show everything that is reachable
336 from the FETCH_HEAD but exclude anything that is reachable from HEAD".
337 Alice already knows everything that leads to her current state (HEAD),
338 and reviews what Bob has in his state (FETCH_HEAD) that she has not
339 seen with this command.
341 If Alice wants to visualize what Bob did since their histories forked
342 she can issue the following command:
344 ------------------------------------------------
345 $ gitk HEAD..FETCH_HEAD
346 ------------------------------------------------
348 This uses the same two-dot range notation we saw earlier with 'git log'.
350 Alice may want to view what both of them did since they forked.
351 She can use three-dot form instead of the two-dot form:
353 ------------------------------------------------
354 $ gitk HEAD...FETCH_HEAD
355 ------------------------------------------------
357 This means "show everything that is reachable from either one, but
358 exclude anything that is reachable from both of them".
360 Please note that these range notation can be used with both gitk
361 and "git log".
363 After inspecting what Bob did, if there is nothing urgent, Alice may
364 decide to continue working without pulling from Bob.  If Bob's history
365 does have something Alice would immediately need, Alice may choose to
366 stash her work-in-progress first, do a "pull", and then finally unstash
367 her work-in-progress on top of the resulting history.
369 When you are working in a small closely knit group, it is not
370 unusual to interact with the same repository over and over
371 again.  By defining 'remote' repository shorthand, you can make
372 it easier:
374 ------------------------------------------------
375 alice$ git remote add bob /home/bob/myrepo
376 ------------------------------------------------
378 With this, Alice can perform the first part of the "pull" operation
379 alone using the 'git fetch' command without merging them with her own
380 branch, using:
382 -------------------------------------
383 alice$ git fetch bob
384 -------------------------------------
386 Unlike the longhand form, when Alice fetches from Bob using a
387 remote repository shorthand set up with 'git remote', what was
388 fetched is stored in a remote tracking branch, in this case
389 `bob/master`.  So after this:
391 -------------------------------------
392 alice$ git log -p master..bob/master
393 -------------------------------------
395 shows a list of all the changes that Bob made since he branched from
396 Alice's master branch.
398 After examining those changes, Alice
399 could merge the changes into her master branch:
401 -------------------------------------
402 alice$ git merge bob/master
403 -------------------------------------
405 This `merge` can also be done by 'pulling from her own remote
406 tracking branch', like this:
408 -------------------------------------
409 alice$ git pull . remotes/bob/master
410 -------------------------------------
412 Note that git pull always merges into the current branch,
413 regardless of what else is given on the command line.
415 Later, Bob can update his repo with Alice's latest changes using
417 -------------------------------------
418 bob$ git pull
419 -------------------------------------
421 Note that he doesn't need to give the path to Alice's repository;
422 when Bob cloned Alice's repository, git stored the location of her
423 repository in the repository configuration, and that location is
424 used for pulls:
426 -------------------------------------
427 bob$ git config --get remote.origin.url
428 /home/alice/project
429 -------------------------------------
431 (The complete configuration created by 'git clone' is visible using
432 `git config -l`, and the linkgit:git-config[1] man page
433 explains the meaning of each option.)
435 Git also keeps a pristine copy of Alice's master branch under the
436 name "origin/master":
438 -------------------------------------
439 bob$ git branch -r
440   origin/master
441 -------------------------------------
443 If Bob later decides to work from a different host, he can still
444 perform clones and pulls using the ssh protocol:
446 -------------------------------------
447 bob$ git clone alice.org:/home/alice/project myrepo
448 -------------------------------------
450 Alternatively, git has a native protocol, or can use rsync or http;
451 see linkgit:git-pull[1] for details.
453 Git can also be used in a CVS-like mode, with a central repository
454 that various users push changes to; see linkgit:git-push[1] and
455 linkgit:gitcvs-migration[7].
457 Exploring history
458 -----------------
460 Git history is represented as a series of interrelated commits.  We
461 have already seen that the 'git log' command can list those commits.
462 Note that first line of each git log entry also gives a name for the
463 commit:
465 -------------------------------------
466 $ git log
467 commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
468 Author: Junio C Hamano <junkio@cox.net>
469 Date:   Tue May 16 17:18:22 2006 -0700
471     merge-base: Clarify the comments on post processing.
472 -------------------------------------
474 We can give this name to 'git show' to see the details about this
475 commit.
477 -------------------------------------
478 $ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
479 -------------------------------------
481 But there are other ways to refer to commits.  You can use any initial
482 part of the name that is long enough to uniquely identify the commit:
484 -------------------------------------
485 $ git show c82a22c39c   # the first few characters of the name are
486                         # usually enough
487 $ git show HEAD         # the tip of the current branch
488 $ git show experimental # the tip of the "experimental" branch
489 -------------------------------------
491 Every commit usually has one "parent" commit
492 which points to the previous state of the project:
494 -------------------------------------
495 $ git show HEAD^  # to see the parent of HEAD
496 $ git show HEAD^^ # to see the grandparent of HEAD
497 $ git show HEAD~4 # to see the great-great grandparent of HEAD
498 -------------------------------------
500 Note that merge commits may have more than one parent:
502 -------------------------------------
503 $ git show HEAD^1 # show the first parent of HEAD (same as HEAD^)
504 $ git show HEAD^2 # show the second parent of HEAD
505 -------------------------------------
507 You can also give commits names of your own; after running
509 -------------------------------------
510 $ git tag v2.5 1b2e1d63ff
511 -------------------------------------
513 you can refer to 1b2e1d63ff by the name "v2.5".  If you intend to
514 share this name with other people (for example, to identify a release
515 version), you should create a "tag" object, and perhaps sign it; see
516 linkgit:git-tag[1] for details.
518 Any git command that needs to know a commit can take any of these
519 names.  For example:
521 -------------------------------------
522 $ git diff v2.5 HEAD     # compare the current HEAD to v2.5
523 $ git branch stable v2.5 # start a new branch named "stable" based
524                          # at v2.5
525 $ git reset --hard HEAD^ # reset your current branch and working
526                          # directory to its state at HEAD^
527 -------------------------------------
529 Be careful with that last command: in addition to losing any changes
530 in the working directory, it will also remove all later commits from
531 this branch.  If this branch is the only branch containing those
532 commits, they will be lost.  Also, don't use 'git reset' on a
533 publicly-visible branch that other developers pull from, as it will
534 force needless merges on other developers to clean up the history.
535 If you need to undo changes that you have pushed, use 'git revert'
536 instead.
538 The 'git grep' command can search for strings in any version of your
539 project, so
541 -------------------------------------
542 $ git grep "hello" v2.5
543 -------------------------------------
545 searches for all occurrences of "hello" in v2.5.
547 If you leave out the commit name, 'git grep' will search any of the
548 files it manages in your current directory.  So
550 -------------------------------------
551 $ git grep "hello"
552 -------------------------------------
554 is a quick way to search just the files that are tracked by git.
556 Many git commands also take sets of commits, which can be specified
557 in a number of ways.  Here are some examples with 'git log':
559 -------------------------------------
560 $ git log v2.5..v2.6            # commits between v2.5 and v2.6
561 $ git log v2.5..                # commits since v2.5
562 $ git log --since="2 weeks ago" # commits from the last 2 weeks
563 $ git log v2.5.. Makefile       # commits since v2.5 which modify
564                                 # Makefile
565 -------------------------------------
567 You can also give 'git log' a "range" of commits where the first is not
568 necessarily an ancestor of the second; for example, if the tips of
569 the branches "stable" and "master" diverged from a common
570 commit some time ago, then
572 -------------------------------------
573 $ git log stable..master
574 -------------------------------------
576 will list commits made in the master branch but not in the
577 stable branch, while
579 -------------------------------------
580 $ git log master..stable
581 -------------------------------------
583 will show the list of commits made on the stable branch but not
584 the master branch.
586 The 'git log' command has a weakness: it must present commits in a
587 list.  When the history has lines of development that diverged and
588 then merged back together, the order in which 'git log' presents
589 those commits is meaningless.
591 Most projects with multiple contributors (such as the Linux kernel,
592 or git itself) have frequent merges, and 'gitk' does a better job of
593 visualizing their history.  For example,
595 -------------------------------------
596 $ gitk --since="2 weeks ago" drivers/
597 -------------------------------------
599 allows you to browse any commits from the last 2 weeks of commits
600 that modified files under the "drivers" directory.  (Note: you can
601 adjust gitk's fonts by holding down the control key while pressing
602 "-" or "+".)
604 Finally, most commands that take filenames will optionally allow you
605 to precede any filename by a commit, to specify a particular version
606 of the file:
608 -------------------------------------
609 $ git diff v2.5:Makefile HEAD:Makefile.in
610 -------------------------------------
612 You can also use 'git show' to see any such file:
614 -------------------------------------
615 $ git show v2.5:Makefile
616 -------------------------------------
618 Next Steps
619 ----------
621 This tutorial should be enough to perform basic distributed revision
622 control for your projects.  However, to fully understand the depth
623 and power of git you need to understand two simple ideas on which it
624 is based:
626   * The object database is the rather elegant system used to
627     store the history of your project--files, directories, and
628     commits.
630   * The index file is a cache of the state of a directory tree,
631     used to create commits, check out working directories, and
632     hold the various trees involved in a merge.
634 Part two of this tutorial explains the object
635 database, the index file, and a few other odds and ends that you'll
636 need to make the most of git. You can find it at linkgit:gittutorial-2[7].
638 If you don't want to continue with that right away, a few other
639 digressions that may be interesting at this point are:
641   * linkgit:git-format-patch[1], linkgit:git-am[1]: These convert
642     series of git commits into emailed patches, and vice versa,
643     useful for projects such as the Linux kernel which rely heavily
644     on emailed patches.
646   * linkgit:git-bisect[1]: When there is a regression in your
647     project, one way to track down the bug is by searching through
648     the history to find the exact commit that's to blame.  Git bisect
649     can help you perform a binary search for that commit.  It is
650     smart enough to perform a close-to-optimal search even in the
651     case of complex non-linear history with lots of merged branches.
653   * linkgit:gitworkflows[7]: Gives an overview of recommended
654     workflows.
656   * link:everyday.html[Everyday GIT with 20 Commands Or So]
658   * linkgit:gitcvs-migration[7]: Git for CVS users.
660 SEE ALSO
661 --------
662 linkgit:gittutorial-2[7],
663 linkgit:gitcvs-migration[7],
664 linkgit:gitcore-tutorial[7],
665 linkgit:gitglossary[7],
666 linkgit:git-help[1],
667 linkgit:gitworkflows[7],
668 link:everyday.html[Everyday git],
669 link:user-manual.html[The Git User's Manual]
673 Part of the linkgit:git[1] suite.