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