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