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