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