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 config --global user.name "Your Name Comes Here" 20$ git 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 104This can be performed multiple times before a commit. Note that this 105is not only for adding new files. Even modified files must be 106added to the set of changes about to be committed. The "git status" 107command gives you a summary of what is included so far for the 108next commit. When done you should use the 'git commit' command to 109make it real. 110 111Note: don't forget to 'add' a file again if you modified it after the 112first 'add' and before 'commit'. Otherwise only the previous added 113state of that file will be committed. This is because git tracks 114content, so what you're really 'add'ing to the commit is the *content* 115of the file in the state it is in when you 'add' it. 116 1172) By using 'git commit -a' directly 118 119This is a quick way to automatically 'add' the content from all files 120that were modified since the previous commit, and perform the actual 121commit without having to separately 'add' them beforehand. This will 122not add content from new files i.e. files that were never added before. 123Those files still have to be added explicitly before performing a 124commit. 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 config --get remote.origin.url 357/home/bob/myrepo 358------------------------------------- 359 360(The complete configuration created by git-clone is visible using 361"git config -l", and the gitlink: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 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 it will 463force needless merges on other developers to clean up the history. 464If you need to undo changes that you have pushed, use gitlink: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 consider with that right away, a few other 568digressions that may be interesting at this point are: 569 570 * gitlink:git-format-patch[1], gitlink: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 * gitlink: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].