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