Documentation/gittutorial.txt

   1 gittutorial(7)
   2 ==============
   3
   4 NAME
   5 ----
   6 gittutorial - A tutorial introduction to git (for version 1.5.1 or newer)
   7
   8 SYNOPSIS
   9 --------
  10 git *
  11
  12 DESCRIPTION
  13 -----------
  14
  15 This tutorial explains how to import a new project into git, make
  16 changes to it, and share changes with other developers.
  17
  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].
  21
  22 First, note that you can get documentation for a command such as "git
  23 diff" with:
  24
  25 ------------------------------------------------
  26 $ man git-diff
  27 ------------------------------------------------
  28
  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:
  32
  33 ------------------------------------------------
  34 $ git config --global user.name "Your Name Comes Here"
  35 $ git config --global user.email you@yourdomain.example.com
  36 ------------------------------------------------
  37
  38
  39 Importing a new project
  40 -----------------------
  41
  42 Assume you have a tarball project.tar.gz with your initial work.  You
  43 can place it under git revision control as follows.
  44
  45 ------------------------------------------------
  46 $ tar xzf project.tar.gz
  47 $ cd project
  48 $ git init
  49 ------------------------------------------------
  50
  51 Git will reply
  52
  53 ------------------------------------------------
  54 Initialized empty Git repository in .git/
  55 ------------------------------------------------
  56
  57 You've now initialized the working directory--you may notice a new
  58 directory created, named ".git".
  59
  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]:
  62
  63 ------------------------------------------------
  64 $ git add .
  65 ------------------------------------------------
  66
  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]:
  70
  71 ------------------------------------------------
  72 $ git commit
  73 ------------------------------------------------
  74
  75 This will prompt you for a commit message.  You've now stored the first
  76 version of your project in git.
  77
  78 Making changes
  79 --------------
  80
  81 Modify some files, then add their updated contents to the index:
  82
  83 ------------------------------------------------
  84 $ git add file1 file2 file3
  85 ------------------------------------------------
  86
  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:
  89
  90 ------------------------------------------------
  91 $ git diff --cached
  92 ------------------------------------------------
  93
  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]:
  97
  98 ------------------------------------------------
  99 $ git status
 100 # On branch master
 101 # Changes to be committed:
 102 #   (use "git reset HEAD <file>..." to unstage)
 103 #
 104 #       modified:   file1
 105 #       modified:   file2
 106 #       modified:   file3
 107 #
 108 ------------------------------------------------
 109
 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:
 112
 113 ------------------------------------------------
 114 $ git commit
 115 ------------------------------------------------
 116
 117 This will again prompt you for a message describing the change, and then
 118 record a new version of the project.
 119
 120 Alternatively, instead of running `git add` beforehand, you can use
 121
 122 ------------------------------------------------
 123 $ git commit -a
 124 ------------------------------------------------
 125
 126 which will automatically notice any modified (but not new) files, add
 127 them to the index, and commit, all in one step.
 128
 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.
 135
 136 Git tracks content not files
 137 ----------------------------
 138
 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.
 145
 146 Viewing project history
 147 -----------------------
 148
 149 At any point you can view the history of your changes using
 150
 151 ------------------------------------------------
 152 $ git log
 153 ------------------------------------------------
 154
 155 If you also want to see complete diffs at each step, use
 156
 157 ------------------------------------------------
 158 $ git log -p
 159 ------------------------------------------------
 160
 161 Often the overview of the change is useful to get a feel of
 162 each step
 163
 164 ------------------------------------------------
 165 $ git log --stat --summary
 166 ------------------------------------------------
 167
 168 Managing branches
 169 -----------------
 170
 171 A single git repository can maintain multiple branches of
 172 development.  To create a new branch named "experimental", use
 173
 174 ------------------------------------------------
 175 $ git branch experimental
 176 ------------------------------------------------
 177
 178 If you now run
 179
 180 ------------------------------------------------
 181 $ git branch
 182 ------------------------------------------------
 183
 184 you'll get a list of all existing branches:
 185
 186 ------------------------------------------------
 187   experimental
 188 * master
 189 ------------------------------------------------
 190
 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
 195
 196 ------------------------------------------------
 197 $ git checkout experimental
 198 ------------------------------------------------
 199
 200 to switch to the experimental branch.  Now edit a file, commit the
 201 change, and switch back to the master branch:
 202
 203 ------------------------------------------------
 204 (edit file)
 205 $ git commit -a
 206 $ git checkout master
 207 ------------------------------------------------
 208
 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.
 211
 212 You can make a different change on the master branch:
 213
 214 ------------------------------------------------
 215 (edit file)
 216 $ git commit -a
 217 ------------------------------------------------
 218
 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
 221
 222 ------------------------------------------------
 223 $ git merge experimental
 224 ------------------------------------------------
 225
 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;
 228
 229 ------------------------------------------------
 230 $ git diff
 231 ------------------------------------------------
 232
 233 will show this.  Once you've edited the files to resolve the
 234 conflicts,
 235
 236 ------------------------------------------------
 237 $ git commit -a
 238 ------------------------------------------------
 239
 240 will commit the result of the merge. Finally,
 241
 242 ------------------------------------------------
 243 $ gitk
 244 ------------------------------------------------
 245
 246 will show a nice graphical representation of the resulting history.
 247
 248 At this point you could delete the experimental branch with
 249
 250 ------------------------------------------------
 251 $ git branch -d experimental
 252 ------------------------------------------------
 253
 254 This command ensures that the changes in the experimental branch are
 255 already in the current branch.
 256
 257 If you develop on a branch crazy-idea, then regret it, you can always
 258 delete the branch with
 259
 260 -------------------------------------
 261 $ git branch -D crazy-idea
 262 -------------------------------------
 263
 264 Branches are cheap and easy, so this is a good way to try something
 265 out.
 266
 267 Using git for collaboration
 268 ---------------------------
 269
 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.
 273
 274 Bob begins with:
 275
 276 ------------------------------------------------
 277 $ git clone /home/alice/project myrepo
 278 ------------------------------------------------
 279
 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.
 283
 284 Bob then makes some changes and commits them:
 285
 286 ------------------------------------------------
 287 (edit files)
 288 $ git commit -a
 289 (repeat as necessary)
 290 ------------------------------------------------
 291
 292 When he's ready, he tells Alice to pull changes from the repository
 293 at /home/bob/myrepo.  She does this with:
 294
 295 ------------------------------------------------
 296 $ cd /home/alice/project
 297 $ git pull /home/bob/myrepo master
 298 ------------------------------------------------
 299
 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.)
 305
 306 The "pull" command thus performs two operations: it fetches changes
 307 from a remote branch, then merges them into the current branch.
 308
 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:
 313
 314 ------------------------------------------------
 315 $ git remote add bob /home/bob/myrepo
 316 ------------------------------------------------
 317
 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:
 321
 322 -------------------------------------
 323 $ git fetch bob
 324 -------------------------------------
 325
 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:
 330
 331 -------------------------------------
 332 $ git log -p master..bob/master
 333 -------------------------------------
 334
 335 shows a list of all the changes that Bob made since he branched from
 336 Alice's master branch.
 337
 338 After examining those changes, Alice
 339 could merge the changes into her master branch:
 340
 341 -------------------------------------
 342 $ git merge bob/master
 343 -------------------------------------
 344
 345 This `merge` can also be done by 'pulling from her own remote
 346 tracking branch', like this:
 347
 348 -------------------------------------
 349 $ git pull . remotes/bob/master
 350 -------------------------------------
 351
 352 Note that git pull always merges into the current branch,
 353 regardless of what else is given on the command line.
 354
 355 Later, Bob can update his repo with Alice's latest changes using
 356
 357 -------------------------------------
 358 $ git pull
 359 -------------------------------------
 360
 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:
 365
 366 -------------------------------------
 367 $ git config --get remote.origin.url
 368 /home/alice/project
 369 -------------------------------------
 370
 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.)
 374
 375 Git also keeps a pristine copy of Alice's master branch under the
 376 name "origin/master":
 377
 378 -------------------------------------
 379 $ git branch -r
 380   origin/master
 381 -------------------------------------
 382
 383 If Bob later decides to work from a different host, he can still
 384 perform clones and pulls using the ssh protocol:
 385
 386 -------------------------------------
 387 $ git clone alice.org:/home/alice/project myrepo
 388 -------------------------------------
 389
 390 Alternatively, git has a native protocol, or can use rsync or http;
 391 see linkgit:git-pull[1] for details.
 392
 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].
 396
 397 Exploring history
 398 -----------------
 399
 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:
 404
 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
 410
 411     merge-base: Clarify the comments on post processing.
 412 -------------------------------------
 413
 414 We can give this name to git show to see the details about this
 415 commit.
 416
 417 -------------------------------------
 418 $ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
 419 -------------------------------------
 420
 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:
 423
 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 -------------------------------------
 430
 431 Every commit usually has one "parent" commit
 432 which points to the previous state of the project:
 433
 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 -------------------------------------
 439
 440 Note that merge commits may have more than one parent:
 441
 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 -------------------------------------
 446
 447 You can also give commits names of your own; after running
 448
 449 -------------------------------------
 450 $ git-tag v2.5 1b2e1d63ff
 451 -------------------------------------
 452
 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.
 457
 458 Any git command that needs to know a commit can take any of these
 459 names.  For example:
 460
 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 -------------------------------------
 468
 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.
 477
 478 The git grep command can search for strings in any version of your
 479 project, so
 480
 481 -------------------------------------
 482 $ git grep "hello" v2.5
 483 -------------------------------------
 484
 485 searches for all occurrences of "hello" in v2.5.
 486
 487 If you leave out the commit name, git grep will search any of the
 488 files it manages in your current directory.  So
 489
 490 -------------------------------------
 491 $ git grep "hello"
 492 -------------------------------------
 493
 494 is a quick way to search just the files that are tracked by git.
 495
 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:
 498
 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 -------------------------------------
 506
 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
 511
 512 -------------------------------------
 513 $ git log stable..experimental
 514 -------------------------------------
 515
 516 will list commits made in the experimental branch but not in the
 517 stable branch, while
 518
 519 -------------------------------------
 520 $ git log experimental..stable
 521 -------------------------------------
 522
 523 will show the list of commits made on the stable branch but not
 524 the experimental branch.
 525
 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.
 530
 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,
 534
 535 -------------------------------------
 536 $ gitk --since="2 weeks ago" drivers/
 537 -------------------------------------
 538
 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 "+".)
 543
 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:
 547
 548 -------------------------------------
 549 $ git diff v2.5:Makefile HEAD:Makefile.in
 550 -------------------------------------
 551
 552 You can also use "git show" to see any such file:
 553
 554 -------------------------------------
 555 $ git show v2.5:Makefile
 556 -------------------------------------
 557
 558 Next Steps
 559 ----------
 560
 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:
 565
 566   * The object database is the rather elegant system used to
 567     store the history of your project--files, directories, and
 568     commits.
 569
 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.
 573
 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.
 577
 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:
 580
 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.
 585
 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.
 592
 593   * link:everyday.html[Everyday GIT with 20 Commands Or So]
 594
 595   * linkgit:gitcvs-migration[7][git for CVS users].
 596
 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]
 605
 606 GIT
 607 ---
 608 Part of the linkgit:git[1] suite.