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