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 whatchanged 84------------------------------------------------ 85 86If you also want to see complete diffs at each step, use 87 88------------------------------------------------ 89$ git whatchanged -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 whatchanged" 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 whatchanged -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 291Keeping track of history 292------------------------ 293 294Git history is represented as a series of interrelated commits. The 295most recent commit in the currently checked-out branch can always be 296referred to as HEAD, and the "parent" of any commit can always be 297referred to by appending a caret, "^", to the end of the name of the 298commit. So, for example, 299 300------------------------------------- 301git diff HEAD^ HEAD 302------------------------------------- 303 304shows the difference between the most-recently checked-in state of 305the tree and the previous state, and 306 307------------------------------------- 308git diff HEAD^^ HEAD^ 309------------------------------------- 310 311shows the difference between that previous state and the state two 312commits ago. Also, HEAD~5 can be used as a shorthand for HEAD^^^^^, 313and more generally HEAD~n can refer to the nth previous commit. 314Commits representing merges have more than one parent, and you can 315specify which parent to follow in that case; see 316gitlink:git-rev-parse[1]. 317 318The name of a branch can also be used to refer to the most recent 319commit on that branch; so you can also say things like 320 321------------------------------------- 322git diff HEAD experimental 323------------------------------------- 324 325to see the difference between the most-recently committed tree in 326the current branch and the most-recently committed tree in the 327experimental branch. 328 329But you may find it more useful to see the list of commits made in 330the experimental branch but not in the current branch, and 331 332------------------------------------- 333git whatchanged HEAD..experimental 334------------------------------------- 335 336will do that, just as 337 338------------------------------------- 339git whatchanged experimental..HEAD 340------------------------------------- 341 342will show the list of commits made on the HEAD but not included in 343experimental. 344 345You can also give commits convenient names of your own: after running 346 347------------------------------------- 348$ git-tag v2.5 HEAD^^ 349------------------------------------- 350 351you can refer to HEAD^^ by the name "v2.5". If you intend to share 352this name with other people (for example, to identify a release 353version), you should create a "tag" object, and perhaps sign it; see 354gitlink:git-tag[1] for details. 355 356You can revisit the old state of a tree, and make further 357modifications if you wish, using git branch: the command 358 359------------------------------------- 360$ git branch stable-release v2.5 361------------------------------------- 362 363will create a new branch named "stable-release" starting from the 364commit which you tagged with the name v2.5. 365 366You can reset the state of any branch to an earlier commit at any 367time with 368 369------------------------------------- 370$ git reset --hard v2.5 371------------------------------------- 372 373This will remove all later commits from this branch and reset the 374working tree to the state it had when the given commit was made. If 375this branch is the only branch containing the later commits, those 376later changes will be lost. Don't use "git reset" on a 377publicly-visible branch that other developers pull from, as git will 378be confused by history that disappears in this way. 379 380Next Steps 381---------- 382 383Some good commands to explore next: 384 385 * gitlink:git-diff[1]: This flexible command does much more than 386 we've seen in the few examples above. 387 388 * gitlink:git-format-patch[1], gitlink:git-am[1]: These convert 389 series of git commits into emailed patches, and vice versa, 390 useful for projects such as the linux kernel which rely heavily 391 on emailed patches. 392 393 * gitlink:git-bisect[1]: When there is a regression in your 394 project, one way to track down the bug is by searching through 395 the history to find the exact commit that's to blame. Git bisect 396 can help you perform a binary search for that commit. It is 397 smart enough to perform a close-to-optimal search even in the 398 case of complex non-linear history with lots of merged branches. 399 400Other good starting points include link:everyday.html[Everday GIT 401with 20 Commands Or So] and link:cvs-migration.html[git for CVS 402users]. Also, link:core-tutorial.html[A short git tutorial] gives an 403introduction to lower-level git commands for advanced users and 404developers.