Documentation/tutorial.txt

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