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