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. 312 313The "pull" command thus performs two operations: it fetches changes 314from a remote branch, then merges them into the current branch. 315 316Note that in general, Alice would want her local changes committed before 317initiating this "pull". If Bob's work conflicts with what Alice did since 318their histories forked, Alice will use her working tree and the index to 319resolve conflicts, and existing local changes will interfere with the 320conflict resolution process (git will still perform the fetch but will 321refuse to merge --- Alice will have to get rid of her local changes in 322some way and pull again when this happens). 323 324Alice can peek at what Bob did without merging first, using the "fetch" 325command; this allows Alice to inspect what Bob did, using a special 326symbol "FETCH_HEAD", in order to determine if he has anything worth 327pulling, like this: 328 329------------------------------------------------ 330alice$ git fetch /home/bob/myrepo master 331alice$ git log -p HEAD..FETCH_HEAD 332------------------------------------------------ 333 334This operation is safe even if Alice has uncommitted local changes. 335The range notation "HEAD..FETCH_HEAD" means "show everything that is reachable 336from the FETCH_HEAD but exclude anything that is reachable from HEAD". 337Alice already knows everything that leads to her current state (HEAD), 338and reviews what Bob has in his state (FETCH_HEAD) that she has not 339seen with this command. 340 341If Alice wants to visualize what Bob did since their histories forked 342she can issue the following command: 343 344------------------------------------------------ 345$ gitk HEAD..FETCH_HEAD 346------------------------------------------------ 347 348This uses the same two-dot range notation we saw earlier with 'git log'. 349 350Alice may want to view what both of them did since they forked. 351She can use three-dot form instead of the two-dot form: 352 353------------------------------------------------ 354$ gitk HEAD...FETCH_HEAD 355------------------------------------------------ 356 357This means "show everything that is reachable from either one, but 358exclude anything that is reachable from both of them". 359 360Please note that these range notation can be used with both gitk 361and "git log". 362 363After inspecting what Bob did, if there is nothing urgent, Alice may 364decide to continue working without pulling from Bob. If Bob's history 365does have something Alice would immediately need, Alice may choose to 366stash her work-in-progress first, do a "pull", and then finally unstash 367her work-in-progress on top of the resulting history. 368 369When you are working in a small closely knit group, it is not 370unusual to interact with the same repository over and over 371again. By defining 'remote' repository shorthand, you can make 372it easier: 373 374------------------------------------------------ 375alice$ git remote add bob /home/bob/myrepo 376------------------------------------------------ 377 378With this, Alice can perform the first part of the "pull" operation 379alone using the 'git fetch' command without merging them with her own 380branch, using: 381 382------------------------------------- 383alice$ git fetch bob 384------------------------------------- 385 386Unlike the longhand form, when Alice fetches from Bob using a 387remote repository shorthand set up with 'git remote', what was 388fetched is stored in a remote tracking branch, in this case 389`bob/master`. So after this: 390 391------------------------------------- 392alice$ git log -p master..bob/master 393------------------------------------- 394 395shows a list of all the changes that Bob made since he branched from 396Alice's master branch. 397 398After examining those changes, Alice 399could merge the changes into her master branch: 400 401------------------------------------- 402alice$ git merge bob/master 403------------------------------------- 404 405This `merge` can also be done by 'pulling from her own remote 406tracking branch', like this: 407 408------------------------------------- 409alice$ git pull . remotes/bob/master 410------------------------------------- 411 412Note that git pull always merges into the current branch, 413regardless of what else is given on the command line. 414 415Later, Bob can update his repo with Alice's latest changes using 416 417------------------------------------- 418bob$ git pull 419------------------------------------- 420 421Note that he doesn't need to give the path to Alice's repository; 422when Bob cloned Alice's repository, git stored the location of her 423repository in the repository configuration, and that location is 424used for pulls: 425 426------------------------------------- 427bob$ git config --get remote.origin.url 428/home/alice/project 429------------------------------------- 430 431(The complete configuration created by 'git clone' is visible using 432`git config -l`, and the linkgit:git-config[1] man page 433explains the meaning of each option.) 434 435Git also keeps a pristine copy of Alice's master branch under the 436name "origin/master": 437 438------------------------------------- 439bob$ git branch -r 440 origin/master 441------------------------------------- 442 443If Bob later decides to work from a different host, he can still 444perform clones and pulls using the ssh protocol: 445 446------------------------------------- 447bob$ git clone alice.org:/home/alice/project myrepo 448------------------------------------- 449 450Alternatively, git has a native protocol, or can use rsync or http; 451see linkgit:git-pull[1] for details. 452 453Git can also be used in a CVS-like mode, with a central repository 454that various users push changes to; see linkgit:git-push[1] and 455linkgit:gitcvs-migration[7]. 456 457Exploring history 458----------------- 459 460Git history is represented as a series of interrelated commits. We 461have already seen that the 'git log' command can list those commits. 462Note that first line of each git log entry also gives a name for the 463commit: 464 465------------------------------------- 466$ git log 467commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 468Author: Junio C Hamano <junkio@cox.net> 469Date: Tue May 16 17:18:22 2006 -0700 470 471 merge-base: Clarify the comments on post processing. 472------------------------------------- 473 474We can give this name to 'git show' to see the details about this 475commit. 476 477------------------------------------- 478$ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 479------------------------------------- 480 481But there are other ways to refer to commits. You can use any initial 482part of the name that is long enough to uniquely identify the commit: 483 484------------------------------------- 485$ git show c82a22c39c # the first few characters of the name are 486 # usually enough 487$ git show HEAD # the tip of the current branch 488$ git show experimental # the tip of the "experimental" branch 489------------------------------------- 490 491Every commit usually has one "parent" commit 492which points to the previous state of the project: 493 494------------------------------------- 495$ git show HEAD^ # to see the parent of HEAD 496$ git show HEAD^^ # to see the grandparent of HEAD 497$ git show HEAD~4 # to see the great-great grandparent of HEAD 498------------------------------------- 499 500Note that merge commits may have more than one parent: 501 502------------------------------------- 503$ git show HEAD^1 # show the first parent of HEAD (same as HEAD^) 504$ git show HEAD^2 # show the second parent of HEAD 505------------------------------------- 506 507You can also give commits names of your own; after running 508 509------------------------------------- 510$ git tag v2.5 1b2e1d63ff 511------------------------------------- 512 513you can refer to 1b2e1d63ff by the name "v2.5". If you intend to 514share this name with other people (for example, to identify a release 515version), you should create a "tag" object, and perhaps sign it; see 516linkgit:git-tag[1] for details. 517 518Any git command that needs to know a commit can take any of these 519names. For example: 520 521------------------------------------- 522$ git diff v2.5 HEAD # compare the current HEAD to v2.5 523$ git branch stable v2.5 # start a new branch named "stable" based 524 # at v2.5 525$ git reset --hard HEAD^ # reset your current branch and working 526 # directory to its state at HEAD^ 527------------------------------------- 528 529Be careful with that last command: in addition to losing any changes 530in the working directory, it will also remove all later commits from 531this branch. If this branch is the only branch containing those 532commits, they will be lost. Also, don't use 'git reset' on a 533publicly-visible branch that other developers pull from, as it will 534force needless merges on other developers to clean up the history. 535If you need to undo changes that you have pushed, use 'git revert' 536instead. 537 538The 'git grep' command can search for strings in any version of your 539project, so 540 541------------------------------------- 542$ git grep "hello" v2.5 543------------------------------------- 544 545searches for all occurrences of "hello" in v2.5. 546 547If you leave out the commit name, 'git grep' will search any of the 548files it manages in your current directory. So 549 550------------------------------------- 551$ git grep "hello" 552------------------------------------- 553 554is a quick way to search just the files that are tracked by git. 555 556Many git commands also take sets of commits, which can be specified 557in a number of ways. Here are some examples with 'git log': 558 559------------------------------------- 560$ git log v2.5..v2.6 # commits between v2.5 and v2.6 561$ git log v2.5.. # commits since v2.5 562$ git log --since="2 weeks ago" # commits from the last 2 weeks 563$ git log v2.5.. Makefile # commits since v2.5 which modify 564 # Makefile 565------------------------------------- 566 567You can also give 'git log' a "range" of commits where the first is not 568necessarily an ancestor of the second; for example, if the tips of 569the branches "stable" and "master" diverged from a common 570commit some time ago, then 571 572------------------------------------- 573$ git log stable..master 574------------------------------------- 575 576will list commits made in the master branch but not in the 577stable branch, while 578 579------------------------------------- 580$ git log master..stable 581------------------------------------- 582 583will show the list of commits made on the stable branch but not 584the master branch. 585 586The 'git log' command has a weakness: it must present commits in a 587list. When the history has lines of development that diverged and 588then merged back together, the order in which 'git log' presents 589those commits is meaningless. 590 591Most projects with multiple contributors (such as the Linux kernel, 592or git itself) have frequent merges, and 'gitk' does a better job of 593visualizing their history. For example, 594 595------------------------------------- 596$ gitk --since="2 weeks ago" drivers/ 597------------------------------------- 598 599allows you to browse any commits from the last 2 weeks of commits 600that modified files under the "drivers" directory. (Note: you can 601adjust gitk's fonts by holding down the control key while pressing 602"-" or "+".) 603 604Finally, most commands that take filenames will optionally allow you 605to precede any filename by a commit, to specify a particular version 606of the file: 607 608------------------------------------- 609$ git diff v2.5:Makefile HEAD:Makefile.in 610------------------------------------- 611 612You can also use 'git show' to see any such file: 613 614------------------------------------- 615$ git show v2.5:Makefile 616------------------------------------- 617 618Next Steps 619---------- 620 621This tutorial should be enough to perform basic distributed revision 622control for your projects. However, to fully understand the depth 623and power of git you need to understand two simple ideas on which it 624is based: 625 626 * The object database is the rather elegant system used to 627 store the history of your project--files, directories, and 628 commits. 629 630 * The index file is a cache of the state of a directory tree, 631 used to create commits, check out working directories, and 632 hold the various trees involved in a merge. 633 634Part two of this tutorial explains the object 635database, the index file, and a few other odds and ends that you'll 636need to make the most of git. You can find it at linkgit:gittutorial-2[7]. 637 638If you don't want to continue with that right away, a few other 639digressions that may be interesting at this point are: 640 641 * linkgit:git-format-patch[1], linkgit:git-am[1]: These convert 642 series of git commits into emailed patches, and vice versa, 643 useful for projects such as the Linux kernel which rely heavily 644 on emailed patches. 645 646 * linkgit:git-bisect[1]: When there is a regression in your 647 project, one way to track down the bug is by searching through 648 the history to find the exact commit that's to blame. Git bisect 649 can help you perform a binary search for that commit. It is 650 smart enough to perform a close-to-optimal search even in the 651 case of complex non-linear history with lots of merged branches. 652 653 * linkgit:gitworkflows[7]: Gives an overview of recommended 654 workflows. 655 656 * link:everyday.html[Everyday GIT with 20 Commands Or So] 657 658 * linkgit:gitcvs-migration[7]: Git for CVS users. 659 660SEE ALSO 661-------- 662linkgit:gittutorial-2[7], 663linkgit:gitcvs-migration[7], 664linkgit:gitcore-tutorial[7], 665linkgit:gitglossary[7], 666linkgit:git-help[1], 667linkgit:gitworkflows[7], 668link:everyday.html[Everyday git], 669link:user-manual.html[The Git User's Manual] 670 671GIT 672--- 673Part of the linkgit:git[1] suite.