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