Move commit_list_count() to commit.c
[git/dscho.git] / Documentation / gittutorial.txt
blobd465aab64e367f1564793b74522d571433d5b53f
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 "git
23 diff" with:
25 ------------------------------------------------
26 $ man git-diff
27 ------------------------------------------------
29 It is a good idea to introduce yourself to git with your name and
30 public email address before doing any operation.  The easiest
31 way to do so is:
33 ------------------------------------------------
34 $ git config --global user.name "Your Name Comes Here"
35 $ git config --global user.email you@yourdomain.example.com
36 ------------------------------------------------
39 Importing a new project
40 -----------------------
42 Assume you have a tarball project.tar.gz with your initial work.  You
43 can place it under git revision control as follows.
45 ------------------------------------------------
46 $ tar xzf project.tar.gz
47 $ cd project
48 $ git init
49 ------------------------------------------------
51 Git will reply
53 ------------------------------------------------
54 Initialized empty Git repository in .git/
55 ------------------------------------------------
57 You've now initialized the working directory--you may notice a new
58 directory created, named ".git".
60 Next, tell git to take a snapshot of the contents of all files under the
61 current directory (note the '.'), with linkgit:git-add[1]:
63 ------------------------------------------------
64 $ git add .
65 ------------------------------------------------
67 This snapshot is now stored in a temporary staging area which git calls
68 the "index".  You can permanently store the contents of the index in the
69 repository with linkgit:git-commit[1]:
71 ------------------------------------------------
72 $ git commit
73 ------------------------------------------------
75 This will prompt you for a commit message.  You've now stored the first
76 version of your project in git.
78 Making changes
79 --------------
81 Modify some files, then add their updated contents to the index:
83 ------------------------------------------------
84 $ git add file1 file2 file3
85 ------------------------------------------------
87 You are now ready to commit.  You can see what is about to be committed
88 using linkgit:git-diff[1] with the --cached option:
90 ------------------------------------------------
91 $ git diff --cached
92 ------------------------------------------------
94 (Without --cached, linkgit:git-diff[1] will show you any changes that
95 you've made but not yet added to the index.)  You can also get a brief
96 summary of the situation with linkgit:git-status[1]:
98 ------------------------------------------------
99 $ git status
100 # On branch master
101 # Changes to be committed:
102 #   (use "git reset HEAD <file>..." to unstage)
104 #       modified:   file1
105 #       modified:   file2
106 #       modified:   file3
108 ------------------------------------------------
110 If you need to make any further adjustments, do so now, and then add any
111 newly modified content to the index.  Finally, commit your changes with:
113 ------------------------------------------------
114 $ git commit
115 ------------------------------------------------
117 This will again prompt you for a message describing the change, and then
118 record a new version of the project.
120 Alternatively, instead of running `git add` beforehand, you can use
122 ------------------------------------------------
123 $ git commit -a
124 ------------------------------------------------
126 which will automatically notice any modified (but not new) files, add
127 them to the index, and commit, all in one step.
129 A note on commit messages: Though not required, it's a good idea to
130 begin the commit message with a single short (less than 50 character)
131 line summarizing the change, followed by a blank line and then a more
132 thorough description.  Tools that turn commits into email, for
133 example, use the first line on the Subject: line and the rest of the
134 commit in the body.
136 Git tracks content not files
137 ----------------------------
139 Many revision control systems provide an "add" command that tells the
140 system to start tracking changes to a new file.  Git's "add" command
141 does something simpler and more powerful: `git add` is used both for new
142 and newly modified files, and in both cases it takes a snapshot of the
143 given files and stages that content in the index, ready for inclusion in
144 the next commit.
146 Viewing project history
147 -----------------------
149 At any point you can view the history of your changes using
151 ------------------------------------------------
152 $ git log
153 ------------------------------------------------
155 If you also want to see complete diffs at each step, use
157 ------------------------------------------------
158 $ git log -p
159 ------------------------------------------------
161 Often the overview of the change is useful to get a feel of
162 each step
164 ------------------------------------------------
165 $ git log --stat --summary
166 ------------------------------------------------
168 Managing branches
169 -----------------
171 A single git repository can maintain multiple branches of
172 development.  To create a new branch named "experimental", use
174 ------------------------------------------------
175 $ git branch experimental
176 ------------------------------------------------
178 If you now run
180 ------------------------------------------------
181 $ git branch
182 ------------------------------------------------
184 you'll get a list of all existing branches:
186 ------------------------------------------------
187   experimental
188 * master
189 ------------------------------------------------
191 The "experimental" branch is the one you just created, and the
192 "master" branch is a default branch that was created for you
193 automatically.  The asterisk marks the branch you are currently on;
194 type
196 ------------------------------------------------
197 $ git checkout experimental
198 ------------------------------------------------
200 to switch to the experimental branch.  Now edit a file, commit the
201 change, and switch back to the master branch:
203 ------------------------------------------------
204 (edit file)
205 $ git commit -a
206 $ git checkout master
207 ------------------------------------------------
209 Check that the change you made is no longer visible, since it was
210 made on the experimental branch and you're back on the master branch.
212 You can make a different change on the master branch:
214 ------------------------------------------------
215 (edit file)
216 $ git commit -a
217 ------------------------------------------------
219 at this point the two branches have diverged, with different changes
220 made in each.  To merge the changes made in experimental into master, run
222 ------------------------------------------------
223 $ git merge experimental
224 ------------------------------------------------
226 If the changes don't conflict, you're done.  If there are conflicts,
227 markers will be left in the problematic files showing the conflict;
229 ------------------------------------------------
230 $ git diff
231 ------------------------------------------------
233 will show this.  Once you've edited the files to resolve the
234 conflicts,
236 ------------------------------------------------
237 $ git commit -a
238 ------------------------------------------------
240 will commit the result of the merge. Finally,
242 ------------------------------------------------
243 $ gitk
244 ------------------------------------------------
246 will show a nice graphical representation of the resulting history.
248 At this point you could delete the experimental branch with
250 ------------------------------------------------
251 $ git branch -d experimental
252 ------------------------------------------------
254 This command ensures that the changes in the experimental branch are
255 already in the current branch.
257 If you develop on a branch crazy-idea, then regret it, you can always
258 delete the branch with
260 -------------------------------------
261 $ git branch -D crazy-idea
262 -------------------------------------
264 Branches are cheap and easy, so this is a good way to try something
265 out.
267 Using git for collaboration
268 ---------------------------
270 Suppose that Alice has started a new project with a git repository in
271 /home/alice/project, and that Bob, who has a home directory on the
272 same machine, wants to contribute.
274 Bob begins with:
276 ------------------------------------------------
277 $ git clone /home/alice/project myrepo
278 ------------------------------------------------
280 This creates a new directory "myrepo" containing a clone of Alice's
281 repository.  The clone is on an equal footing with the original
282 project, possessing its own copy of the original project's history.
284 Bob then makes some changes and commits them:
286 ------------------------------------------------
287 (edit files)
288 $ git commit -a
289 (repeat as necessary)
290 ------------------------------------------------
292 When he's ready, he tells Alice to pull changes from the repository
293 at /home/bob/myrepo.  She does this with:
295 ------------------------------------------------
296 $ cd /home/alice/project
297 $ git pull /home/bob/myrepo master
298 ------------------------------------------------
300 This merges the changes from Bob's "master" branch into Alice's
301 current branch.  If Alice has made her own changes in the meantime,
302 then she may need to manually fix any conflicts.  (Note that the
303 "master" argument in the above command is actually unnecessary, as it
304 is the default.)
306 The "pull" command thus performs two operations: it fetches changes
307 from a remote branch, then merges them into the current branch.
309 When you are working in a small closely knit group, it is not
310 unusual to interact with the same repository over and over
311 again.  By defining 'remote' repository shorthand, you can make
312 it easier:
314 ------------------------------------------------
315 $ git remote add bob /home/bob/myrepo
316 ------------------------------------------------
318 With this, Alice can perform the first operation alone using the
319 "git fetch" command without merging them with her own branch,
320 using:
322 -------------------------------------
323 $ git fetch bob
324 -------------------------------------
326 Unlike the longhand form, when Alice fetches from Bob using a
327 remote repository shorthand set up with `git remote`, what was
328 fetched is stored in a remote tracking branch, in this case
329 `bob/master`.  So after this:
331 -------------------------------------
332 $ git log -p master..bob/master
333 -------------------------------------
335 shows a list of all the changes that Bob made since he branched from
336 Alice's master branch.
338 After examining those changes, Alice
339 could merge the changes into her master branch:
341 -------------------------------------
342 $ git merge bob/master
343 -------------------------------------
345 This `merge` can also be done by 'pulling from her own remote
346 tracking branch', like this:
348 -------------------------------------
349 $ git pull . remotes/bob/master
350 -------------------------------------
352 Note that git pull always merges into the current branch,
353 regardless of what else is given on the command line.
355 Later, Bob can update his repo with Alice's latest changes using
357 -------------------------------------
358 $ git pull
359 -------------------------------------
361 Note that he doesn't need to give the path to Alice's repository;
362 when Bob cloned Alice's repository, git stored the location of her
363 repository in the repository configuration, and that location is
364 used for pulls:
366 -------------------------------------
367 $ git config --get remote.origin.url
368 /home/alice/project
369 -------------------------------------
371 (The complete configuration created by git-clone is visible using
372 "git config -l", and the linkgit:git-config[1] man page
373 explains the meaning of each option.)
375 Git also keeps a pristine copy of Alice's master branch under the
376 name "origin/master":
378 -------------------------------------
379 $ git branch -r
380   origin/master
381 -------------------------------------
383 If Bob later decides to work from a different host, he can still
384 perform clones and pulls using the ssh protocol:
386 -------------------------------------
387 $ git clone alice.org:/home/alice/project myrepo
388 -------------------------------------
390 Alternatively, git has a native protocol, or can use rsync or http;
391 see linkgit:git-pull[1] for details.
393 Git can also be used in a CVS-like mode, with a central repository
394 that various users push changes to; see linkgit:git-push[1] and
395 linkgit:gitcvs-migration[7][git for CVS users].
397 Exploring history
398 -----------------
400 Git history is represented as a series of interrelated commits.  We
401 have already seen that the git log command can list those commits.
402 Note that first line of each git log entry also gives a name for the
403 commit:
405 -------------------------------------
406 $ git log
407 commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
408 Author: Junio C Hamano <junkio@cox.net>
409 Date:   Tue May 16 17:18:22 2006 -0700
411     merge-base: Clarify the comments on post processing.
412 -------------------------------------
414 We can give this name to git show to see the details about this
415 commit.
417 -------------------------------------
418 $ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
419 -------------------------------------
421 But there are other ways to refer to commits.  You can use any initial
422 part of the name that is long enough to uniquely identify the commit:
424 -------------------------------------
425 $ git show c82a22c39c   # the first few characters of the name are
426                         # usually enough
427 $ git show HEAD         # the tip of the current branch
428 $ git show experimental # the tip of the "experimental" branch
429 -------------------------------------
431 Every commit usually has one "parent" commit
432 which points to the previous state of the project:
434 -------------------------------------
435 $ git show HEAD^  # to see the parent of HEAD
436 $ git show HEAD^^ # to see the grandparent of HEAD
437 $ git show HEAD~4 # to see the great-great grandparent of HEAD
438 -------------------------------------
440 Note that merge commits may have more than one parent:
442 -------------------------------------
443 $ git show HEAD^1 # show the first parent of HEAD (same as HEAD^)
444 $ git show HEAD^2 # show the second parent of HEAD
445 -------------------------------------
447 You can also give commits names of your own; after running
449 -------------------------------------
450 $ git-tag v2.5 1b2e1d63ff
451 -------------------------------------
453 you can refer to 1b2e1d63ff by the name "v2.5".  If you intend to
454 share this name with other people (for example, to identify a release
455 version), you should create a "tag" object, and perhaps sign it; see
456 linkgit:git-tag[1] for details.
458 Any git command that needs to know a commit can take any of these
459 names.  For example:
461 -------------------------------------
462 $ git diff v2.5 HEAD     # compare the current HEAD to v2.5
463 $ git branch stable v2.5 # start a new branch named "stable" based
464                          # at v2.5
465 $ git reset --hard HEAD^ # reset your current branch and working
466                          # directory to its state at HEAD^
467 -------------------------------------
469 Be careful with that last command: in addition to losing any changes
470 in the working directory, it will also remove all later commits from
471 this branch.  If this branch is the only branch containing those
472 commits, they will be lost.  Also, don't use "git reset" on a
473 publicly-visible branch that other developers pull from, as it will
474 force needless merges on other developers to clean up the history.
475 If you need to undo changes that you have pushed, use linkgit:git-revert[1]
476 instead.
478 The git grep command can search for strings in any version of your
479 project, so
481 -------------------------------------
482 $ git grep "hello" v2.5
483 -------------------------------------
485 searches for all occurrences of "hello" in v2.5.
487 If you leave out the commit name, git grep will search any of the
488 files it manages in your current directory.  So
490 -------------------------------------
491 $ git grep "hello"
492 -------------------------------------
494 is a quick way to search just the files that are tracked by git.
496 Many git commands also take sets of commits, which can be specified
497 in a number of ways.  Here are some examples with git log:
499 -------------------------------------
500 $ git log v2.5..v2.6            # commits between v2.5 and v2.6
501 $ git log v2.5..                # commits since v2.5
502 $ git log --since="2 weeks ago" # commits from the last 2 weeks
503 $ git log v2.5.. Makefile       # commits since v2.5 which modify
504                                 # Makefile
505 -------------------------------------
507 You can also give git log a "range" of commits where the first is not
508 necessarily an ancestor of the second; for example, if the tips of
509 the branches "stable-release" and "master" diverged from a common
510 commit some time ago, then
512 -------------------------------------
513 $ git log stable..experimental
514 -------------------------------------
516 will list commits made in the experimental branch but not in the
517 stable branch, while
519 -------------------------------------
520 $ git log experimental..stable
521 -------------------------------------
523 will show the list of commits made on the stable branch but not
524 the experimental branch.
526 The "git log" command has a weakness: it must present commits in a
527 list.  When the history has lines of development that diverged and
528 then merged back together, the order in which "git log" presents
529 those commits is meaningless.
531 Most projects with multiple contributors (such as the linux kernel,
532 or git itself) have frequent merges, and gitk does a better job of
533 visualizing their history.  For example,
535 -------------------------------------
536 $ gitk --since="2 weeks ago" drivers/
537 -------------------------------------
539 allows you to browse any commits from the last 2 weeks of commits
540 that modified files under the "drivers" directory.  (Note: you can
541 adjust gitk's fonts by holding down the control key while pressing
542 "-" or "+".)
544 Finally, most commands that take filenames will optionally allow you
545 to precede any filename by a commit, to specify a particular version
546 of the file:
548 -------------------------------------
549 $ git diff v2.5:Makefile HEAD:Makefile.in
550 -------------------------------------
552 You can also use "git show" to see any such file:
554 -------------------------------------
555 $ git show v2.5:Makefile
556 -------------------------------------
558 Next Steps
559 ----------
561 This tutorial should be enough to perform basic distributed revision
562 control for your projects.  However, to fully understand the depth
563 and power of git you need to understand two simple ideas on which it
564 is based:
566   * The object database is the rather elegant system used to
567     store the history of your project--files, directories, and
568     commits.
570   * The index file is a cache of the state of a directory tree,
571     used to create commits, check out working directories, and
572     hold the various trees involved in a merge.
574 linkgit:gittutorial-2[7][Part two of this tutorial] explains the object
575 database, the index file, and a few other odds and ends that you'll
576 need to make the most of git.
578 If you don't want to continue with that right away, a few other
579 digressions that may be interesting at this point are:
581   * linkgit:git-format-patch[1], linkgit:git-am[1]: These convert
582     series of git commits into emailed patches, and vice versa,
583     useful for projects such as the linux kernel which rely heavily
584     on emailed patches.
586   * linkgit:git-bisect[1]: When there is a regression in your
587     project, one way to track down the bug is by searching through
588     the history to find the exact commit that's to blame.  Git bisect
589     can help you perform a binary search for that commit.  It is
590     smart enough to perform a close-to-optimal search even in the
591     case of complex non-linear history with lots of merged branches.
593   * link:everyday.html[Everyday GIT with 20 Commands Or So]
595   * linkgit:gitcvs-migration[7][git for CVS users].
597 SEE ALSO
598 --------
599 linkgit:gittutorial-2[7],
600 linkgit:gitcvs-migration[7],
601 linkgit:gitcore-tutorial[7],
602 linkgit:gitglossary[7],
603 link:everyday.html[Everyday git],
604 link:user-manual.html[The Git User's Manual]
608 Part of the linkgit:git[1] suite.