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.