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