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 14It is a good idea to introduce yourself to git with your name and 15public email address before doing any operation. The easiest 16way to do so is: 17 18------------------------------------------------ 19$ git repo-config --global user.name "Your Name Comes Here" 20$ git repo-config --global user.email you@yourdomain.example.com 21------------------------------------------------ 22 23 24Importing a new project 25----------------------- 26 27Assume you have a tarball project.tar.gz with your initial work. You 28can place it under git revision control as follows. 29 30------------------------------------------------ 31$ tar xzf project.tar.gz 32$ cd project 33$ git init 34------------------------------------------------ 35 36Git will reply 37 38------------------------------------------------ 39Initialized empty Git repository in .git/ 40------------------------------------------------ 41 42You've now initialized the working directory--you may notice a new 43directory created, named ".git". Tell git that you want it to track 44every file under the current directory (note the '.') with: 45 46------------------------------------------------ 47$ git add . 48------------------------------------------------ 49 50Finally, 51 52------------------------------------------------ 53$ git commit 54------------------------------------------------ 55 56will prompt you for a commit message, then record the current state 57of all the files to the repository. 58 59Making changes 60-------------- 61 62Try modifying some files, then run 63 64------------------------------------------------ 65$ git diff 66------------------------------------------------ 67 68to review your changes. When you're done, tell git that you 69want the updated contents of these files in the commit and then 70make a commit, like this: 71 72------------------------------------------------ 73$ git add file1 file2 file3 74$ git commit 75------------------------------------------------ 76 77This will again prompt your for a message describing the change, and then 78record the new versions of the files you listed. 79 80Alternatively, instead of running `git add` beforehand, you can use 81 82------------------------------------------------ 83$ git commit -a 84------------------------------------------------ 85 86which will automatically notice modified (but not new) files. 87 88A note on commit messages: Though not required, it's a good idea to 89begin the commit message with a single short (less than 50 character) 90line summarizing the change, followed by a blank line and then a more 91thorough description. Tools that turn commits into email, for 92example, use the first line on the Subject: line and the rest of the 93commit in the body. 94 95 96Git tracks content not files 97---------------------------- 98 99With git you have to explicitly "add" all the changed _content_ you 100want to commit together. This can be done in a few different ways: 101 1021) By using 'git add <file_spec>...' 103 104 This can be performed multiple times before a commit. Note that this 105 is not only for adding new files. Even modified files must be 106 added to the set of changes about to be committed. The "git status" 107 command gives you a summary of what is included so far for the 108 next commit. When done you should use the 'git commit' command to 109 make it real. 110 111 Note: don't forget to 'add' a file again if you modified it after the 112 first 'add' and before 'commit'. Otherwise only the previous added 113 state of that file will be committed. This is because git tracks 114 content, so what you're really 'add'ing to the commit is the *content* 115 of the file in the state it is in when you 'add' it. 116 1172) By using 'git commit -a' directly 118 119 This is a quick way to automatically 'add' the content from all files 120 that were modified since the previous commit, and perform the actual 121 commit without having to separately 'add' them beforehand. This will 122 not add content from new files i.e. files that were never added before. 123 Those files still have to be added explicitly before performing a 124 commit. 125 126But here's a twist. If you do 'git commit <file1> <file2> ...' then only 127the changes belonging to those explicitly specified files will be 128committed, entirely bypassing the current "added" changes. Those "added" 129changes will still remain available for a subsequent commit though. 130 131However, for normal usage you only have to remember 'git add' + 'git commit' 132and/or 'git commit -a'. 133 134 135Viewing the changelog 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 298You can perform the first operation alone using the "git fetch" 299command. For example, Alice could create a temporary branch just to 300track Bob's changes, without merging them with her own, using: 301 302------------------------------------- 303$ git fetch /home/bob/myrepo master:bob-incoming 304------------------------------------- 305 306which fetches the changes from Bob's master branch into a new branch 307named bob-incoming. Then 308 309------------------------------------- 310$ git log -p master..bob-incoming 311------------------------------------- 312 313shows a list of all the changes that Bob made since he branched from 314Alice's master branch. 315 316After examining those changes, and possibly fixing things, Alice 317could merge the changes into her master branch: 318 319------------------------------------- 320$ git checkout master 321$ git merge bob-incoming 322------------------------------------- 323 324The last command is a merge from the "bob-incoming" branch in Alice's 325own repository. 326 327Alice could also perform both steps at once with: 328 329------------------------------------- 330$ git pull /home/bob/myrepo master:bob-incoming 331------------------------------------- 332 333This is just like the "git pull /home/bob/myrepo master" that we saw 334before, except that it also stores the unmerged changes from bob's 335master branch in bob-incoming before merging them into Alice's 336current branch. Note that git pull always merges into the current 337branch, regardless of what else is given on the commandline. 338 339Later, Bob can update his repo with Alice's latest changes using 340 341------------------------------------- 342$ git pull 343------------------------------------- 344 345Note that he doesn't need to give the path to Alice's repository; 346when Bob cloned Alice's repository, git stored the location of her 347repository in the repository configuration, and that location is 348used for pulls: 349 350------------------------------------- 351$ git repo-config --get remote.origin.url 352/home/bob/myrepo 353------------------------------------- 354 355(The complete configuration created by git-clone is visible using 356"git repo-config -l", and the gitlink:git-repo-config[1] man page 357explains the meaning of each option.) 358 359Git also keeps a pristine copy of Alice's master branch under the 360name "origin/master": 361 362------------------------------------- 363$ git branch -r 364 origin/master 365------------------------------------- 366 367If Bob later decides to work from a different host, he can still 368perform clones and pulls using the ssh protocol: 369 370------------------------------------- 371$ git clone alice.org:/home/alice/project myrepo 372------------------------------------- 373 374Alternatively, git has a native protocol, or can use rsync or http; 375see gitlink:git-pull[1] for details. 376 377Git can also be used in a CVS-like mode, with a central repository 378that various users push changes to; see gitlink:git-push[1] and 379link:cvs-migration.html[git for CVS users]. 380 381Exploring history 382----------------- 383 384Git history is represented as a series of interrelated commits. We 385have already seen that the git log command can list those commits. 386Note that first line of each git log entry also gives a name for the 387commit: 388 389------------------------------------- 390$ git log 391commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 392Author: Junio C Hamano <junkio@cox.net> 393Date: Tue May 16 17:18:22 2006 -0700 394 395 merge-base: Clarify the comments on post processing. 396------------------------------------- 397 398We can give this name to git show to see the details about this 399commit. 400 401------------------------------------- 402$ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7 403------------------------------------- 404 405But there are other ways to refer to commits. You can use any initial 406part of the name that is long enough to uniquely identify the commit: 407 408------------------------------------- 409$ git show c82a22c39c # the first few characters of the name are 410 # usually enough 411$ git show HEAD # the tip of the current branch 412$ git show experimental # the tip of the "experimental" branch 413------------------------------------- 414 415Every commit usually has one "parent" commit 416which points to the previous state of the project: 417 418------------------------------------- 419$ git show HEAD^ # to see the parent of HEAD 420$ git show HEAD^^ # to see the grandparent of HEAD 421$ git show HEAD~4 # to see the great-great grandparent of HEAD 422------------------------------------- 423 424Note that merge commits may have more than one parent: 425 426------------------------------------- 427$ git show HEAD^1 # show the first parent of HEAD (same as HEAD^) 428$ git show HEAD^2 # show the second parent of HEAD 429------------------------------------- 430 431You can also give commits names of your own; after running 432 433------------------------------------- 434$ git-tag v2.5 1b2e1d63ff 435------------------------------------- 436 437you can refer to 1b2e1d63ff by the name "v2.5". If you intend to 438share this name with other people (for example, to identify a release 439version), you should create a "tag" object, and perhaps sign it; see 440gitlink:git-tag[1] for details. 441 442Any git command that needs to know a commit can take any of these 443names. For example: 444 445------------------------------------- 446$ git diff v2.5 HEAD # compare the current HEAD to v2.5 447$ git branch stable v2.5 # start a new branch named "stable" based 448 # at v2.5 449$ git reset --hard HEAD^ # reset your current branch and working 450 # directory to its state at HEAD^ 451------------------------------------- 452 453Be careful with that last command: in addition to losing any changes 454in the working directory, it will also remove all later commits from 455this branch. If this branch is the only branch containing those 456commits, they will be lost. (Also, don't use "git reset" on a 457publicly-visible branch that other developers pull from, as git will 458be confused by history that disappears in this way.) 459 460The git grep command can search for strings in any version of your 461project, so 462 463------------------------------------- 464$ git grep "hello" v2.5 465------------------------------------- 466 467searches for all occurrences of "hello" in v2.5. 468 469If you leave out the commit name, git grep will search any of the 470files it manages in your current directory. So 471 472------------------------------------- 473$ git grep "hello" 474------------------------------------- 475 476is a quick way to search just the files that are tracked by git. 477 478Many git commands also take sets of commits, which can be specified 479in a number of ways. Here are some examples with git log: 480 481------------------------------------- 482$ git log v2.5..v2.6 # commits between v2.5 and v2.6 483$ git log v2.5.. # commits since v2.5 484$ git log --since="2 weeks ago" # commits from the last 2 weeks 485$ git log v2.5.. Makefile # commits since v2.5 which modify 486 # Makefile 487------------------------------------- 488 489You can also give git log a "range" of commits where the first is not 490necessarily an ancestor of the second; for example, if the tips of 491the branches "stable-release" and "master" diverged from a common 492commit some time ago, then 493 494------------------------------------- 495$ git log stable..experimental 496------------------------------------- 497 498will list commits made in the experimental branch but not in the 499stable branch, while 500 501------------------------------------- 502$ git log experimental..stable 503------------------------------------- 504 505will show the list of commits made on the stable branch but not 506the experimental branch. 507 508The "git log" command has a weakness: it must present commits in a 509list. When the history has lines of development that diverged and 510then merged back together, the order in which "git log" presents 511those commits is meaningless. 512 513Most projects with multiple contributors (such as the linux kernel, 514or git itself) have frequent merges, and gitk does a better job of 515visualizing their history. For example, 516 517------------------------------------- 518$ gitk --since="2 weeks ago" drivers/ 519------------------------------------- 520 521allows you to browse any commits from the last 2 weeks of commits 522that modified files under the "drivers" directory. (Note: you can 523adjust gitk's fonts by holding down the control key while pressing 524"-" or "+".) 525 526Finally, most commands that take filenames will optionally allow you 527to precede any filename by a commit, to specify a particular version 528of the file: 529 530------------------------------------- 531$ git diff v2.5:Makefile HEAD:Makefile.in 532------------------------------------- 533 534You can also use "git show" to see any such file: 535 536------------------------------------- 537$ git show v2.5:Makefile 538------------------------------------- 539 540Next Steps 541---------- 542 543This tutorial should be enough to perform basic distributed revision 544control for your projects. However, to fully understand the depth 545and power of git you need to understand two simple ideas on which it 546is based: 547 548 * The object database is the rather elegant system used to 549 store the history of your project--files, directories, and 550 commits. 551 552 * The index file is a cache of the state of a directory tree, 553 used to create commits, check out working directories, and 554 hold the various trees involved in a merge. 555 556link:tutorial-2.html[Part two of this tutorial] explains the object 557database, the index file, and a few other odds and ends that you'll 558need to make the most of git. 559 560If you don't want to consider with that right away, a few other 561digressions that may be interesting at this point are: 562 563 * gitlink:git-format-patch[1], gitlink:git-am[1]: These convert 564 series of git commits into emailed patches, and vice versa, 565 useful for projects such as the linux kernel which rely heavily 566 on emailed patches. 567 568 * gitlink:git-bisect[1]: When there is a regression in your 569 project, one way to track down the bug is by searching through 570 the history to find the exact commit that's to blame. Git bisect 571 can help you perform a binary search for that commit. It is 572 smart enough to perform a close-to-optimal search even in the 573 case of complex non-linear history with lots of merged branches. 574 575 * link:everyday.html[Everyday GIT with 20 Commands Or So] 576 577 * link:cvs-migration.html[git for CVS users].