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