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