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