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