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 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, you 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 commandline. 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 repo-config --get remote.origin.url 357/home/bob/myrepo 358------------------------------------- 359 360(The complete configuration created by git-clone is visible using 361"git repo-config -l", and the gitlink:git-repo-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 gitlink: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 gitlink: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 445gitlink: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 git will 463be confused by history that disappears in this way.) 464 465The git grep command can search for strings in any version of your 466project, so 467 468------------------------------------- 469$ git grep "hello" v2.5 470------------------------------------- 471 472searches for all occurrences of "hello" in v2.5. 473 474If you leave out the commit name, git grep will search any of the 475files it manages in your current directory. So 476 477------------------------------------- 478$ git grep "hello" 479------------------------------------- 480 481is a quick way to search just the files that are tracked by git. 482 483Many git commands also take sets of commits, which can be specified 484in a number of ways. Here are some examples with git log: 485 486------------------------------------- 487$ git log v2.5..v2.6 # commits between v2.5 and v2.6 488$ git log v2.5.. # commits since v2.5 489$ git log --since="2 weeks ago" # commits from the last 2 weeks 490$ git log v2.5.. Makefile # commits since v2.5 which modify 491 # Makefile 492------------------------------------- 493 494You can also give git log a "range" of commits where the first is not 495necessarily an ancestor of the second; for example, if the tips of 496the branches "stable-release" and "master" diverged from a common 497commit some time ago, then 498 499------------------------------------- 500$ git log stable..experimental 501------------------------------------- 502 503will list commits made in the experimental branch but not in the 504stable branch, while 505 506------------------------------------- 507$ git log experimental..stable 508------------------------------------- 509 510will show the list of commits made on the stable branch but not 511the experimental branch. 512 513The "git log" command has a weakness: it must present commits in a 514list. When the history has lines of development that diverged and 515then merged back together, the order in which "git log" presents 516those commits is meaningless. 517 518Most projects with multiple contributors (such as the linux kernel, 519or git itself) have frequent merges, and gitk does a better job of 520visualizing their history. For example, 521 522------------------------------------- 523$ gitk --since="2 weeks ago" drivers/ 524------------------------------------- 525 526allows you to browse any commits from the last 2 weeks of commits 527that modified files under the "drivers" directory. (Note: you can 528adjust gitk's fonts by holding down the control key while pressing 529"-" or "+".) 530 531Finally, most commands that take filenames will optionally allow you 532to precede any filename by a commit, to specify a particular version 533of the file: 534 535------------------------------------- 536$ git diff v2.5:Makefile HEAD:Makefile.in 537------------------------------------- 538 539You can also use "git show" to see any such file: 540 541------------------------------------- 542$ git show v2.5:Makefile 543------------------------------------- 544 545Next Steps 546---------- 547 548This tutorial should be enough to perform basic distributed revision 549control for your projects. However, to fully understand the depth 550and power of git you need to understand two simple ideas on which it 551is based: 552 553 * The object database is the rather elegant system used to 554 store the history of your project--files, directories, and 555 commits. 556 557 * The index file is a cache of the state of a directory tree, 558 used to create commits, check out working directories, and 559 hold the various trees involved in a merge. 560 561link:tutorial-2.html[Part two of this tutorial] explains the object 562database, the index file, and a few other odds and ends that you'll 563need to make the most of git. 564 565If you don't want to consider with that right away, a few other 566digressions that may be interesting at this point are: 567 568 * gitlink:git-format-patch[1], gitlink:git-am[1]: These convert 569 series of git commits into emailed patches, and vice versa, 570 useful for projects such as the linux kernel which rely heavily 571 on emailed patches. 572 573 * gitlink:git-bisect[1]: When there is a regression in your 574 project, one way to track down the bug is by searching through 575 the history to find the exact commit that's to blame. Git bisect 576 can help you perform a binary search for that commit. It is 577 smart enough to perform a close-to-optimal search even in the 578 case of complex non-linear history with lots of merged branches. 579 580 * link:everyday.html[Everyday GIT with 20 Commands Or So] 581 582 * link:cvs-migration.html[git for CVS users].