1Git User's Manual 2_________________ 3 4This manual is designed to be readable by someone with basic unix 5commandline skills, but no previous knowledge of git. 6 7Chapter 1 gives a brief overview of git commands, without any 8explanation; you may prefer to skip to chapter 2 on a first reading. 9 10Chapters 2 and 3 explain how to fetch and study a project using 11git--the tools you'd need to build and test a particular version of a 12software project, to search for regressions, and so on. 13 14Chapter 4 explains how to do development with git, and chapter 5 how 15to share that development with others. 16 17Further chapters cover more specialized topics. 18 19Comprehensive reference documentation is available through the man 20pages. For a command such as "git clone", just use 21 22------------------------------------------------ 23$ man git-clone 24------------------------------------------------ 25 26Git Quick Start 27=============== 28 29This is a quick summary of the major commands; the following chapters 30will explain how these work in more detail. 31 32Creating a new repository 33------------------------- 34 35From a tarball: 36 37----------------------------------------------- 38$ tar xzf project.tar.gz 39$ cd project 40$ git init 41Initialized empty Git repository in .git/ 42$ git add . 43$ git commit 44----------------------------------------------- 45 46From a remote repository: 47 48----------------------------------------------- 49$ git clone git://example.com/pub/project.git 50$ cd project 51----------------------------------------------- 52 53Managing branches 54----------------- 55 56----------------------------------------------- 57$ git branch # list all branches in this repo 58$ git checkout test # switch working directory to branch "test" 59$ git branch new # create branch "new" starting at current HEAD 60$ git branch -d new # delete branch "new" 61----------------------------------------------- 62 63Instead of basing new branch on current HEAD (the default), use: 64 65----------------------------------------------- 66$ git branch new test # branch named "test" 67$ git branch new v2.6.15 # tag named v2.6.15 68$ git branch new HEAD^ # commit before the most recent 69$ git branch new HEAD^^ # commit before that 70$ git branch new test~10 # ten commits before tip of branch "test" 71----------------------------------------------- 72 73Create and switch to a new branch at the same time: 74 75----------------------------------------------- 76$ git checkout -b new v2.6.15 77----------------------------------------------- 78 79Update and examine branches from the repository you cloned from: 80 81----------------------------------------------- 82$ git fetch # update 83$ git branch -r # list 84 origin/master 85 origin/next 86 ... 87$ git branch checkout -b masterwork origin/master 88----------------------------------------------- 89 90Fetch a branch from a different repository, and give it a new 91name in your repository: 92 93----------------------------------------------- 94$ git fetch git://example.com/project.git theirbranch:mybranch 95$ git fetch git://example.com/project.git v2.6.15:mybranch 96----------------------------------------------- 97 98Keep a list of repositories you work with regularly: 99 100----------------------------------------------- 101$ git remote add example git://example.com/project.git 102$ git remote # list remote repositories 103example 104origin 105$ git remote show example # get details 106* remote example 107 URL: git://example.com/project.git 108 Tracked remote branches 109 master next ... 110$ git fetch example # update branches from example 111$ git branch -r # list all remote branches 112----------------------------------------------- 113 114 115Exploring history 116----------------- 117 118----------------------------------------------- 119$ gitk # visualize and browse history 120$ git log # list all commits 121$ git log src/ # ...modifying src/ 122$ git log v2.6.15..v2.6.16 # ...in v2.6.16, not in v2.6.15 123$ git log master..test # ...in branch test, not in branch master 124$ git log test..master # ...in branch master, but not in test 125$ git log test...master # ...in one branch, not in both 126$ git log -S'foo()' # ...where difference contain "foo()" 127$ git log --since="2 weeks ago" 128$ git log -p # show patches as well 129$ git show # most recent commit 130$ git diff v2.6.15..v2.6.16 # diff between two tagged versions 131$ git diff v2.6.15..HEAD # diff with current head 132$ git grep "foo()" # search working directory for "foo()" 133$ git grep v2.6.15 "foo()" # search old tree for "foo()" 134$ git show v2.6.15:a.txt # look at old version of a.txt 135----------------------------------------------- 136 137Search for regressions: 138 139----------------------------------------------- 140$ git bisect start 141$ git bisect bad # current version is bad 142$ git bisect good v2.6.13-rc2 # last known good revision 143Bisecting: 675 revisions left to test after this 144 # test here, then: 145$ git bisect good # if this revision is good, or 146$ git bisect bad # if this revision is bad. 147 # repeat until done. 148----------------------------------------------- 149 150Making changes 151-------------- 152 153Make sure git knows who to blame: 154 155------------------------------------------------ 156$ cat >~/.gitconfig <<\EOF 157[user] 158name = Your Name Comes Here 159email = you@yourdomain.example.com 160EOF 161------------------------------------------------ 162 163Select file contents to include in the next commit, then make the 164commit: 165 166----------------------------------------------- 167$ git add a.txt # updated file 168$ git add b.txt # new file 169$ git rm c.txt # old file 170$ git commit 171----------------------------------------------- 172 173Or, prepare and create the commit in one step: 174 175----------------------------------------------- 176$ git commit d.txt # use latest content only of d.txt 177$ git commit -a # use latest content of all tracked files 178----------------------------------------------- 179 180Merging 181------- 182 183----------------------------------------------- 184$ git merge test # merge branch "test" into the current branch 185$ git pull git://example.com/project.git master 186 # fetch and merge in remote branch 187$ git pull . test # equivalent to git merge test 188----------------------------------------------- 189 190Sharing your changes 191-------------------- 192 193Importing or exporting patches: 194 195----------------------------------------------- 196$ git format-patch origin..HEAD # format a patch for each commit 197 # in HEAD but not in origin 198$ git-am mbox # import patches from the mailbox "mbox" 199----------------------------------------------- 200 201Fetch a branch in a different git repository, then merge into the 202current branch: 203 204----------------------------------------------- 205$ git pull git://example.com/project.git theirbranch 206----------------------------------------------- 207 208Store the fetched branch into a local branch before merging into the 209current branch: 210 211----------------------------------------------- 212$ git pull git://example.com/project.git theirbranch:mybranch 213----------------------------------------------- 214 215After creating commits on a local branch, update the remote 216branch with your commits: 217 218----------------------------------------------- 219$ git push ssh://example.com/project.git mybranch:theirbranch 220----------------------------------------------- 221 222When remote and local branch are both named "test": 223 224----------------------------------------------- 225$ git push ssh://example.com/project.git test 226----------------------------------------------- 227 228Shortcut version for a frequently used remote repository: 229 230----------------------------------------------- 231$ git remote add example ssh://example.com/project.git 232$ git push example test 233----------------------------------------------- 234 235Repository maintenance 236---------------------- 237 238Check for corruption: 239 240----------------------------------------------- 241$ git fsck 242----------------------------------------------- 243 244Recompress, remove unused cruft: 245 246----------------------------------------------- 247$ git gc 248----------------------------------------------- 249 250Repositories and Branches 251========================= 252 253How to get a git repository 254--------------------------- 255 256It will be useful to have a git repository to experiment with as you 257read this manual. 258 259The best way to get one is by using the gitlink:git-clone[1] command 260to download a copy of an existing repository for a project that you 261are interested in. If you don't already have a project in mind, here 262are some interesting examples: 263 264------------------------------------------------ 265 # git itself (approx. 10MB download): 266$ git clone git://git.kernel.org/pub/scm/git/git.git 267 # the linux kernel (approx. 150MB download): 268$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git 269------------------------------------------------ 270 271The initial clone may be time-consuming for a large project, but you 272will only need to clone once. 273 274The clone command creates a new directory named after the project 275("git" or "linux-2.6" in the examples above). After you cd into this 276directory, you will see that it contains a copy of the project files, 277together with a special top-level directory named ".git", which 278contains all the information about the history of the project. 279 280In most of the following, examples will be taken from one of the two 281repositories above. 282 283How to check out a different version of a project 284------------------------------------------------- 285 286Git is best thought of as a tool for storing the history of a 287collection of files. It stores the history as a compressed 288collection of interrelated snapshots (versions) of the project's 289contents. 290 291A single git repository may contain multiple branches. Each branch 292is a bookmark referencing a particular point in the project history. 293The gitlink:git-branch[1] command shows you the list of branches: 294 295------------------------------------------------ 296$ git branch 297* master 298------------------------------------------------ 299 300A freshly cloned repository contains a single branch, named "master", 301and the working directory contains the version of the project 302referred to by the master branch. 303 304Most projects also use tags. Tags, like branches, are references 305into the project's history, and can be listed using the 306gitlink:git-tag[1] command: 307 308------------------------------------------------ 309$ git tag -l 310v2.6.11 311v2.6.11-tree 312v2.6.12 313v2.6.12-rc2 314v2.6.12-rc3 315v2.6.12-rc4 316v2.6.12-rc5 317v2.6.12-rc6 318v2.6.13 319... 320------------------------------------------------ 321 322Tags are expected to always point at the same version of a project, 323while branches are expected to advance as development progresses. 324 325Create a new branch pointing to one of these versions and check it 326out using gitlink:git-checkout[1]: 327 328------------------------------------------------ 329$ git checkout -b new v2.6.13 330------------------------------------------------ 331 332The working directory then reflects the contents that the project had 333when it was tagged v2.6.13, and gitlink:git-branch[1] shows two 334branches, with an asterisk marking the currently checked-out branch: 335 336------------------------------------------------ 337$ git branch 338 master 339* new 340------------------------------------------------ 341 342If you decide that you'd rather see version 2.6.17, you can modify 343the current branch to point at v2.6.17 instead, with 344 345------------------------------------------------ 346$ git reset --hard v2.6.17 347------------------------------------------------ 348 349Note that if the current branch was your only reference to a 350particular point in history, then resetting that branch may leave you 351with no way to find the history it used to point to; so use this 352command carefully. 353 354Understanding History: Commits 355------------------------------ 356 357Every change in the history of a project is represented by a commit. 358The gitlink:git-show[1] command shows the most recent commit on the 359current branch: 360 361------------------------------------------------ 362$ git show 363commit 2b5f6dcce5bf94b9b119e9ed8d537098ec61c3d2 364Author: Jamal Hadi Salim <hadi@cyberus.ca> 365Date: Sat Dec 2 22:22:25 2006 -0800 366 367 [XFRM]: Fix aevent structuring to be more complete. 368 369 aevents can not uniquely identify an SA. We break the ABI with this 370 patch, but consensus is that since it is not yet utilized by any 371 (known) application then it is fine (better do it now than later). 372 373 Signed-off-by: Jamal Hadi Salim <hadi@cyberus.ca> 374 Signed-off-by: David S. Miller <davem@davemloft.net> 375 376diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt 377index 8be626f..d7aac9d 100644 378--- a/Documentation/networking/xfrm_sync.txt 379+++ b/Documentation/networking/xfrm_sync.txt 380@@ -47,10 +47,13 @@ aevent_id structure looks like: 381 382 struct xfrm_aevent_id { 383 struct xfrm_usersa_id sa_id; 384+ xfrm_address_t saddr; 385 __u32 flags; 386+ __u32 reqid; 387 }; 388... 389------------------------------------------------ 390 391As you can see, a commit shows who made the latest change, what they 392did, and why. 393 394Every commit has a 40-hexdigit id, sometimes called the "object name" 395or the "SHA1 id", shown on the first line of the "git show" output. 396You can usually refer to a commit by a shorter name, such as a tag or a 397branch name, but this longer name can also be useful. Most 398importantly, it is a globally unique name for this commit: so if you 399tell somebody else the object name (for example in email), then you are 400guaranteed that name will refer to the same commit in their repository 401that you it does in yours (assuming their repository has that commit at 402all). 403 404Understanding history: commits, parents, and reachability 405~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 406 407Every commit (except the very first commit in a project) also has a 408parent commit which shows what happened before this commit. 409Following the chain of parents will eventually take you back to the 410beginning of the project. 411 412However, the commits do not form a simple list; git allows lines of 413development to diverge and then reconverge, and the point where two 414lines of development reconverge is called a "merge". The commit 415representing a merge can therefore have more than one parent, with 416each parent representing the most recent commit on one of the lines 417of development leading to that point. 418 419The best way to see how this works is using the gitlink:gitk[1] 420command; running gitk now on a git repository and looking for merge 421commits will help understand how the git organizes history. 422 423In the following, we say that commit X is "reachable" from commit Y 424if commit X is an ancestor of commit Y. Equivalently, you could say 425that Y is a descendent of X, or that there is a chain of parents 426leading from commit Y to commit X. 427 428Undestanding history: History diagrams 429~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 430 431We will sometimes represent git history using diagrams like the one 432below. Commits are shown as "o", and the links between them with 433lines drawn with - / and \. Time goes left to right: 434 435 o--o--o <-- Branch A 436 / 437 o--o--o <-- master 438 \ 439 o--o--o <-- Branch B 440 441If we need to talk about a particular commit, the character "o" may 442be replaced with another letter or number. 443 444Understanding history: What is a branch? 445~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 446 447Though we've been using the word "branch" to mean a kind of reference 448to a particular commit, the word branch is also commonly used to 449refer to the line of commits leading up to that point. In the 450example above, git may think of the branch named "A" as just a 451pointer to one particular commit, but we may refer informally to the 452line of three commits leading up to that point as all being part of 453"branch A". 454 455If we need to make it clear that we're just talking about the most 456recent commit on the branch, we may refer to that commit as the 457"head" of the branch. 458 459Manipulating branches 460--------------------- 461 462Creating, deleting, and modifying branches is quick and easy; here's 463a summary of the commands: 464 465git branch:: 466 list all branches 467git branch <branch>:: 468 create a new branch named <branch>, referencing the same 469 point in history as the current branch 470git branch <branch> <start-point>:: 471 create a new branch named <branch>, referencing 472 <start-point>, which may be specified any way you like, 473 including using a branch name or a tag name 474git branch -d <branch>:: 475 delete the branch <branch>; if the branch you are deleting 476 points to a commit which is not reachable from this branch, 477 this command will fail with a warning. 478git branch -D <branch>:: 479 even if the branch points to a commit not reachable 480 from the current branch, you may know that that commit 481 is still reachable from some other branch or tag. In that 482 case it is safe to use this command to force git to delete 483 the branch. 484git checkout <branch>:: 485 make the current branch <branch>, updating the working 486 directory to reflect the version referenced by <branch> 487git checkout -b <new> <start-point>:: 488 create a new branch <new> referencing <start-point>, and 489 check it out. 490 491It is also useful to know that the special symbol "HEAD" can always 492be used to refer to the current branch. 493 494Examining branches from a remote repository 495------------------------------------------- 496 497The "master" branch that was created at the time you cloned is a copy 498of the HEAD in the repository that you cloned from. That repository 499may also have had other branches, though, and your local repository 500keeps branches which track each of those remote branches, which you 501can view using the "-r" option to gitlink:git-branch[1]: 502 503------------------------------------------------ 504$ git branch -r 505 origin/HEAD 506 origin/html 507 origin/maint 508 origin/man 509 origin/master 510 origin/next 511 origin/pu 512 origin/todo 513------------------------------------------------ 514 515You cannot check out these remote-tracking branches, but you can 516examine them on a branch of your own, just as you would a tag: 517 518------------------------------------------------ 519$ git checkout -b my-todo-copy origin/todo 520------------------------------------------------ 521 522Note that the name "origin" is just the name that git uses by default 523to refer to the repository that you cloned from. 524 525[[how-git-stores-references]] 526Naming branches, tags, and other references 527------------------------------------------- 528 529Branches, remote-tracking branches, and tags are all references to 530commits. All references are named with a slash-separated path name 531starting with "refs"; the names we've been using so far are actually 532shorthand: 533 534 - The branch "test" is short for "refs/heads/test". 535 - The tag "v2.6.18" is short for "refs/tags/v2.6.18". 536 - "origin/master" is short for "refs/remotes/origin/master". 537 538The full name is occasionally useful if, for example, there ever 539exists a tag and a branch with the same name. 540 541As another useful shortcut, if the repository "origin" posesses only 542a single branch, you can refer to that branch as just "origin". 543 544More generally, if you have defined a remote repository named 545"example", you can refer to the branch in that repository as 546"example". And for a repository with multiple branches, this will 547refer to the branch designated as the "HEAD" branch. 548 549For the complete list of paths which git checks for references, and 550the order it uses to decide which to choose when there are multiple 551references with the same shorthand name, see the "SPECIFYING 552REVISIONS" section of gitlink:git-rev-parse[1]. 553 554[[Updating-a-repository-with-git-fetch]] 555Updating a repository with git fetch 556------------------------------------ 557 558Eventually the developer cloned from will do additional work in her 559repository, creating new commits and advancing the branches to point 560at the new commits. 561 562The command "git fetch", with no arguments, will update all of the 563remote-tracking branches to the latest version found in her 564repository. It will not touch any of your own branches--not even the 565"master" branch that was created for you on clone. 566 567Fetching branches from other repositories 568----------------------------------------- 569 570You can also track branches from repositories other than the one you 571cloned from, using gitlink:git-remote[1]: 572 573------------------------------------------------- 574$ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git 575$ git fetch 576* refs/remotes/linux-nfs/master: storing branch 'master' ... 577 commit: bf81b46 578------------------------------------------------- 579 580New remote-tracking branches will be stored under the shorthand name 581that you gave "git remote add", in this case linux-nfs: 582 583------------------------------------------------- 584$ git branch -r 585linux-nfs/master 586origin/master 587------------------------------------------------- 588 589If you run "git fetch <remote>" later, the tracking branches for the 590named <remote> will be updated. 591 592If you examine the file .git/config, you will see that git has added 593a new stanza: 594 595------------------------------------------------- 596$ cat .git/config 597... 598[remote "linux-nfs"] 599 url = git://linux-nfs.org/~bfields/git.git 600 fetch = +refs/heads/*:refs/remotes/linux-nfs-read/* 601... 602------------------------------------------------- 603 604This is what causes git to track the remote's branches; you may modify 605or delete these configuration options by editing .git/config with a 606text editor. (See the "CONFIGURATION FILE" section of 607gitlink:git-config[1] for details.) 608 609Exploring git history 610===================== 611 612Git is best thought of as a tool for storing the history of a 613collection of files. It does this by storing compressed snapshots of 614the contents of a file heirarchy, together with "commits" which show 615the relationships between these snapshots. 616 617Git provides extremely flexible and fast tools for exploring the 618history of a project. 619 620We start with one specialized tool which is useful for finding the 621commit that introduced a bug into a project. 622 623How to use bisect to find a regression 624-------------------------------------- 625 626Suppose version 2.6.18 of your project worked, but the version at 627"master" crashes. Sometimes the best way to find the cause of such a 628regression is to perform a brute-force search through the project's 629history to find the particular commit that caused the problem. The 630gitlink:git-bisect[1] command can help you do this: 631 632------------------------------------------------- 633$ git bisect start 634$ git bisect good v2.6.18 635$ git bisect bad master 636Bisecting: 3537 revisions left to test after this 637[65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6] 638------------------------------------------------- 639 640If you run "git branch" at this point, you'll see that git has 641temporarily moved you to a new branch named "bisect". This branch 642points to a commit (with commit id 65934...) that is reachable from 643v2.6.19 but not from v2.6.18. Compile and test it, and see whether 644it crashes. Assume it does crash. Then: 645 646------------------------------------------------- 647$ git bisect bad 648Bisecting: 1769 revisions left to test after this 649[7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings 650------------------------------------------------- 651 652checks out an older version. Continue like this, telling git at each 653stage whether the version it gives you is good or bad, and notice 654that the number of revisions left to test is cut approximately in 655half each time. 656 657After about 13 tests (in this case), it will output the commit id of 658the guilty commit. You can then examine the commit with 659gitlink:git-show[1], find out who wrote it, and mail them your bug 660report with the commit id. Finally, run 661 662------------------------------------------------- 663$ git bisect reset 664------------------------------------------------- 665 666to return you to the branch you were on before and delete the 667temporary "bisect" branch. 668 669Note that the version which git-bisect checks out for you at each 670point is just a suggestion, and you're free to try a different 671version if you think it would be a good idea. For example, 672occasionally you may land on a commit that broke something unrelated; 673run 674 675------------------------------------------------- 676$ git bisect-visualize 677------------------------------------------------- 678 679which will run gitk and label the commit it chose with a marker that 680says "bisect". Chose a safe-looking commit nearby, note its commit 681id, and check it out with: 682 683------------------------------------------------- 684$ git reset --hard fb47ddb2db... 685------------------------------------------------- 686 687then test, run "bisect good" or "bisect bad" as appropriate, and 688continue. 689 690Naming commits 691-------------- 692 693We have seen several ways of naming commits already: 694 695 - 40-hexdigit SHA1 id 696 - branch name: refers to the commit at the head of the given 697 branch 698 - tag name: refers to the commit pointed to by the given tag 699 (we've seen branches and tags are special cases of 700 <<how-git-stores-references,references>>). 701 - HEAD: refers to the head of the current branch 702 703There are many more; see the "SPECIFYING REVISIONS" section of the 704gitlink:git-rev-parse[1] man page for the complete list of ways to 705name revisions. Some examples: 706 707------------------------------------------------- 708$ git show fb47ddb2 # the first few characters of the SHA1 id 709 # are usually enough to specify it uniquely 710$ git show HEAD^ # the parent of the HEAD commit 711$ git show HEAD^^ # the grandparent 712$ git show HEAD~4 # the great-great-grandparent 713------------------------------------------------- 714 715Recall that merge commits may have more than one parent; by default, 716^ and ~ follow the first parent listed in the commit, but you can 717also choose: 718 719------------------------------------------------- 720$ git show HEAD^1 # show the first parent of HEAD 721$ git show HEAD^2 # show the second parent of HEAD 722------------------------------------------------- 723 724In addition to HEAD, there are several other special names for 725commits: 726 727Merges (to be discussed later), as well as operations such as 728git-reset, which change the currently checked-out commit, generally 729set ORIG_HEAD to the value HEAD had before the current operation. 730 731The git-fetch operation always stores the head of the last fetched 732branch in FETCH_HEAD. For example, if you run git fetch without 733specifying a local branch as the target of the operation 734 735------------------------------------------------- 736$ git fetch git://example.com/proj.git theirbranch 737------------------------------------------------- 738 739the fetched commits will still be available from FETCH_HEAD. 740 741When we discuss merges we'll also see the special name MERGE_HEAD, 742which refers to the other branch that we're merging in to the current 743branch. 744 745The gitlink:git-rev-parse[1] command is a low-level command that is 746occasionally useful for translating some name for a commit to the SHA1 id for 747that commit: 748 749------------------------------------------------- 750$ git rev-parse origin 751e05db0fd4f31dde7005f075a84f96b360d05984b 752------------------------------------------------- 753 754Creating tags 755------------- 756 757We can also create a tag to refer to a particular commit; after 758running 759 760------------------------------------------------- 761$ git-tag stable-1 1b2e1d63ff 762------------------------------------------------- 763 764You can use stable-1 to refer to the commit 1b2e1d63ff. 765 766This creates a "lightweight" tag. If the tag is a tag you wish to 767share with others, and possibly sign cryptographically, then you 768should create a tag object instead; see the gitlink:git-tag[1] man 769page for details. 770 771Browsing revisions 772------------------ 773 774The gitlink:git-log[1] command can show lists of commits. On its 775own, it shows all commits reachable from the parent commit; but you 776can also make more specific requests: 777 778------------------------------------------------- 779$ git log v2.5.. # commits since (not reachable from) v2.5 780$ git log test..master # commits reachable from master but not test 781$ git log master..test # ...reachable from test but not master 782$ git log master...test # ...reachable from either test or master, 783 # but not both 784$ git log --since="2 weeks ago" # commits from the last 2 weeks 785$ git log Makefile # commits which modify Makefile 786$ git log fs/ # ... which modify any file under fs/ 787$ git log -S'foo()' # commits which add or remove any file data 788 # matching the string 'foo()' 789------------------------------------------------- 790 791And of course you can combine all of these; the following finds 792commits since v2.5 which touch the Makefile or any file under fs: 793 794------------------------------------------------- 795$ git log v2.5.. Makefile fs/ 796------------------------------------------------- 797 798You can also ask git log to show patches: 799 800------------------------------------------------- 801$ git log -p 802------------------------------------------------- 803 804See the "--pretty" option in the gitlink:git-log[1] man page for more 805display options. 806 807Note that git log starts with the most recent commit and works 808backwards through the parents; however, since git history can contain 809multiple independant lines of development, the particular order that 810commits are listed in may be somewhat arbitrary. 811 812Generating diffs 813---------------- 814 815You can generate diffs between any two versions using 816gitlink:git-diff[1]: 817 818------------------------------------------------- 819$ git diff master..test 820------------------------------------------------- 821 822Sometimes what you want instead is a set of patches: 823 824------------------------------------------------- 825$ git format-patch master..test 826------------------------------------------------- 827 828will generate a file with a patch for each commit reachable from test 829but not from master. Note that if master also has commits which are 830not reachable from test, then the combined result of these patches 831will not be the same as the diff produced by the git-diff example. 832 833Viewing old file versions 834------------------------- 835 836You can always view an old version of a file by just checking out the 837correct revision first. But sometimes it is more convenient to be 838able to view an old version of a single file without checking 839anything out; this command does that: 840 841------------------------------------------------- 842$ git show v2.5:fs/locks.c 843------------------------------------------------- 844 845Before the colon may be anything that names a commit, and after it 846may be any path to a file tracked by git. 847 848Examples 849-------- 850 851Check whether two branches point at the same history 852~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 853 854Suppose you want to check whether two branches point at the same point 855in history. 856 857------------------------------------------------- 858$ git diff origin..master 859------------------------------------------------- 860 861will tell you whether the contents of the project are the same at the 862two branches; in theory, however, it's possible that the same project 863contents could have been arrived at by two different historical 864routes. You could compare the SHA1 id's: 865 866------------------------------------------------- 867$ git rev-list origin 868e05db0fd4f31dde7005f075a84f96b360d05984b 869$ git rev-list master 870e05db0fd4f31dde7005f075a84f96b360d05984b 871------------------------------------------------- 872 873Or you could recall that the ... operator selects all commits 874contained reachable from either one reference or the other but not 875both: so 876 877------------------------------------------------- 878$ git log origin...master 879------------------------------------------------- 880 881will return no commits when the two branches are equal. 882 883Find first tagged version including a given fix 884~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 885 886Suppose you know that the commit e05db0fd fixed a certain problem. 887You'd like to find the earliest tagged release that contains that 888fix. 889 890Of course, there may be more than one answer--if the history branched 891after commit e05db0fd, then there could be multiple "earliest" tagged 892releases. 893 894You could just visually inspect the commits since e05db0fd: 895 896------------------------------------------------- 897$ gitk e05db0fd.. 898------------------------------------------------- 899 900Or you can use gitlink:git-name-rev[1], which will give the commit a 901name based on any tag it finds pointing to one of the commit's 902descendants: 903 904------------------------------------------------- 905$ git name-rev e05db0fd 906e05db0fd tags/v1.5.0-rc1^0~23 907------------------------------------------------- 908 909The gitlink:git-describe[1] command does the opposite, naming the 910revision using a tag on which the given commit is based: 911 912------------------------------------------------- 913$ git describe e05db0fd 914v1.5.0-rc0-ge05db0f 915------------------------------------------------- 916 917but that may sometimes help you guess which tags might come after the 918given commit. 919 920If you just want to verify whether a given tagged version contains a 921given commit, you could use gitlink:git-merge-base[1]: 922 923------------------------------------------------- 924$ git merge-base e05db0fd v1.5.0-rc1 925e05db0fd4f31dde7005f075a84f96b360d05984b 926------------------------------------------------- 927 928The merge-base command finds a common ancestor of the given commits, 929and always returns one or the other in the case where one is a 930descendant of the other; so the above output shows that e05db0fd 931actually is an ancestor of v1.5.0-rc1. 932 933Alternatively, note that 934 935------------------------------------------------- 936$ git log v1.5.0-rc1..e05db0fd 937------------------------------------------------- 938 939will produce empty output if and only if v1.5.0-rc1 includes e05db0fd, 940because it outputs only commits that are not reachable from v1.5.0-rc1. 941 942As yet another alternative, the gitlink:git-show-branch[1] command lists 943the commits reachable from its arguments with a display on the left-hand 944side that indicates which arguments that commit is reachable from. So, 945you can run something like 946 947------------------------------------------------- 948$ git show-branch e05db0fd v1.5.0-rc0 v1.5.0-rc1 v1.5.0-rc2 949! [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if 950available 951 ! [v1.5.0-rc0] GIT v1.5.0 preview 952 ! [v1.5.0-rc1] GIT v1.5.0-rc1 953 ! [v1.5.0-rc2] GIT v1.5.0-rc2 954... 955------------------------------------------------- 956 957then search for a line that looks like 958 959------------------------------------------------- 960+ ++ [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if 961available 962------------------------------------------------- 963 964Which shows that e05db0fd is reachable from itself, from v1.5.0-rc1, and 965from v1.5.0-rc2, but not from v1.5.0-rc0. 966 967 968Developing with git 969=================== 970 971Telling git your name 972--------------------- 973 974Before creating any commits, you should introduce yourself to git. The 975easiest way to do so is: 976 977------------------------------------------------ 978$ cat >~/.gitconfig <<\EOF 979[user] 980 name = Your Name Comes Here 981 email = you@yourdomain.example.com 982EOF 983------------------------------------------------ 984 985(See the "CONFIGURATION FILE" section of gitlink:git-config[1] for 986details on the configuration file.) 987 988 989Creating a new repository 990------------------------- 991 992Creating a new repository from scratch is very easy: 993 994------------------------------------------------- 995$ mkdir project 996$ cd project 997$ git init 998------------------------------------------------- 9991000If you have some initial content (say, a tarball):10011002-------------------------------------------------1003$ tar -xzvf project.tar.gz1004$ cd project1005$ git init1006$ git add . # include everything below ./ in the first commit:1007$ git commit1008-------------------------------------------------10091010[[how-to-make-a-commit]]1011how to make a commit1012--------------------10131014Creating a new commit takes three steps:10151016 1. Making some changes to the working directory using your1017 favorite editor.1018 2. Telling git about your changes.1019 3. Creating the commit using the content you told git about1020 in step 2.10211022In practice, you can interleave and repeat steps 1 and 2 as many1023times as you want: in order to keep track of what you want committed1024at step 3, git maintains a snapshot of the tree's contents in a1025special staging area called "the index."10261027At the beginning, the content of the index will be identical to1028that of the HEAD. The command "git diff --cached", which shows1029the difference between the HEAD and the index, should therefore1030produce no output at that point.10311032Modifying the index is easy:10331034To update the index with the new contents of a modified file, use10351036-------------------------------------------------1037$ git add path/to/file1038-------------------------------------------------10391040To add the contents of a new file to the index, use10411042-------------------------------------------------1043$ git add path/to/file1044-------------------------------------------------10451046To remove a file from the index and from the working tree,10471048-------------------------------------------------1049$ git rm path/to/file1050-------------------------------------------------10511052After each step you can verify that10531054-------------------------------------------------1055$ git diff --cached1056-------------------------------------------------10571058always shows the difference between the HEAD and the index file--this1059is what you'd commit if you created the commit now--and that10601061-------------------------------------------------1062$ git diff1063-------------------------------------------------10641065shows the difference between the working tree and the index file.10661067Note that "git add" always adds just the current contents of a file1068to the index; further changes to the same file will be ignored unless1069you run git-add on the file again.10701071When you're ready, just run10721073-------------------------------------------------1074$ git commit1075-------------------------------------------------10761077and git will prompt you for a commit message and then create the new1078commmit. Check to make sure it looks like what you expected with10791080-------------------------------------------------1081$ git show1082-------------------------------------------------10831084As a special shortcut,10851086-------------------------------------------------1087$ git commit -a1088-------------------------------------------------10891090will update the index with any files that you've modified or removed1091and create a commit, all in one step.10921093A number of commands are useful for keeping track of what you're1094about to commit:10951096-------------------------------------------------1097$ git diff --cached # difference between HEAD and the index; what1098 # would be commited if you ran "commit" now.1099$ git diff # difference between the index file and your1100 # working directory; changes that would not1101 # be included if you ran "commit" now.1102$ git status # a brief per-file summary of the above.1103-------------------------------------------------11041105creating good commit messages1106-----------------------------11071108Though not required, it's a good idea to begin the commit message1109with a single short (less than 50 character) line summarizing the1110change, followed by a blank line and then a more thorough1111description. Tools that turn commits into email, for example, use1112the first line on the Subject line and the rest of the commit in the1113body.11141115how to merge1116------------11171118You can rejoin two diverging branches of development using1119gitlink:git-merge[1]:11201121-------------------------------------------------1122$ git merge branchname1123-------------------------------------------------11241125merges the development in the branch "branchname" into the current1126branch. If there are conflicts--for example, if the same file is1127modified in two different ways in the remote branch and the local1128branch--then you are warned; the output may look something like this:11291130-------------------------------------------------1131$ git pull . next1132Trying really trivial in-index merge...1133fatal: Merge requires file-level merging1134Nope.1135Merging HEAD with 77976da35a11db4580b80ae27e8d65caf52080861136Merging:113715e2162 world113877976da goodbye1139found 1 common ancestor(s):1140d122ed4 initial1141Auto-merging file.txt1142CONFLICT (content): Merge conflict in file.txt1143Automatic merge failed; fix conflicts and then commit the result.1144-------------------------------------------------11451146Conflict markers are left in the problematic files, and after1147you resolve the conflicts manually, you can update the index1148with the contents and run git commit, as you normally would when1149creating a new file.11501151If you examine the resulting commit using gitk, you will see that it1152has two parents, one pointing to the top of the current branch, and1153one to the top of the other branch.11541155In more detail:11561157[[resolving-a-merge]]1158Resolving a merge1159-----------------11601161When a merge isn't resolved automatically, git leaves the index and1162the working tree in a special state that gives you all the1163information you need to help resolve the merge.11641165Files with conflicts are marked specially in the index, so until you1166resolve the problem and update the index, git commit will fail:11671168-------------------------------------------------1169$ git commit1170file.txt: needs merge1171-------------------------------------------------11721173Also, git status will list those files as "unmerged".11741175All of the changes that git was able to merge automatically are1176already added to the index file, so gitlink:git-diff[1] shows only1177the conflicts. Also, it uses a somewhat unusual syntax:11781179-------------------------------------------------1180$ git diff1181diff --cc file.txt1182index 802992c,2b60207..00000001183--- a/file.txt1184+++ b/file.txt1185@@@ -1,1 -1,1 +1,5 @@@1186++<<<<<<< HEAD:file.txt1187 +Hello world1188++=======1189+ Goodbye1190++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt1191-------------------------------------------------11921193Recall that the commit which will be commited after we resolve this1194conflict will have two parents instead of the usual one: one parent1195will be HEAD, the tip of the current branch; the other will be the1196tip of the other branch, which is stored temporarily in MERGE_HEAD.11971198The diff above shows the differences between the working-tree version1199of file.txt and two previous version: one version from HEAD, and one1200from MERGE_HEAD. So instead of preceding each line by a single "+"1201or "-", it now uses two columns: the first column is used for1202differences between the first parent and the working directory copy,1203and the second for differences between the second parent and the1204working directory copy. Thus after resolving the conflict in the1205obvious way, the diff will look like:12061207-------------------------------------------------1208$ git diff1209diff --cc file.txt1210index 802992c,2b60207..00000001211--- a/file.txt1212+++ b/file.txt1213@@@ -1,1 -1,1 +1,1 @@@1214- Hello world1215 -Goodbye1216++Goodbye world1217-------------------------------------------------12181219This shows that our resolved version deleted "Hello world" from the1220first parent, deleted "Goodbye" from the second parent, and added1221"Goodbye world", which was previously absent from both.12221223The gitlink:git-log[1] command also provides special help for merges:12241225-------------------------------------------------1226$ git log --merge1227-------------------------------------------------12281229This will list all commits which exist only on HEAD or on MERGE_HEAD,1230and which touch an unmerged file.12311232We can now add the resolved version to the index and commit:12331234-------------------------------------------------1235$ git add file.txt1236$ git commit1237-------------------------------------------------12381239Note that the commit message will already be filled in for you with1240some information about the merge. Normally you can just use this1241default message unchanged, but you may add additional commentary of1242your own if desired.12431244[[undoing-a-merge]]1245undoing a merge1246---------------12471248If you get stuck and decide to just give up and throw the whole mess1249away, you can always return to the pre-merge state with12501251-------------------------------------------------1252$ git reset --hard HEAD1253-------------------------------------------------12541255Or, if you've already commited the merge that you want to throw away,12561257-------------------------------------------------1258$ git reset --hard HEAD^1259-------------------------------------------------12601261However, this last command can be dangerous in some cases--never1262throw away a commit you have already committed if that commit may1263itself have been merged into another branch, as doing so may confuse1264further merges.12651266Fast-forward merges1267-------------------12681269There is one special case not mentioned above, which is treated1270differently. Normally, a merge results in a merge commit, with two1271parents, one pointing at each of the two lines of development that1272were merged.12731274However, if one of the two lines of development is completely1275contained within the other--so every commit present in the one is1276already contained in the other--then git just performs a1277<<fast-forwards,fast forward>>; the head of the current branch is1278moved forward to point at the head of the merged-in branch, without1279any new commits being created.12801281Fixing mistakes1282---------------12831284If you've messed up the working tree, but haven't yet committed your1285mistake, you can return the entire working tree to the last committed1286state with12871288-------------------------------------------------1289$ git reset --hard HEAD1290-------------------------------------------------12911292If you make a commit that you later wish you hadn't, there are two1293fundamentally different ways to fix the problem:12941295 1. You can create a new commit that undoes whatever was done1296 by the previous commit. This is the correct thing if your1297 mistake has already been made public.12981299 2. You can go back and modify the old commit. You should1300 never do this if you have already made the history public;1301 git does not normally expect the "history" of a project to1302 change, and cannot correctly perform repeated merges from1303 a branch that has had its history changed.13041305Fixing a mistake with a new commit1306~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~13071308Creating a new commit that reverts an earlier change is very easy;1309just pass the gitlink:git-revert[1] command a reference to the bad1310commit; for example, to revert the most recent commit:13111312-------------------------------------------------1313$ git revert HEAD1314-------------------------------------------------13151316This will create a new commit which undoes the change in HEAD. You1317will be given a chance to edit the commit message for the new commit.13181319You can also revert an earlier change, for example, the next-to-last:13201321-------------------------------------------------1322$ git revert HEAD^1323-------------------------------------------------13241325In this case git will attempt to undo the old change while leaving1326intact any changes made since then. If more recent changes overlap1327with the changes to be reverted, then you will be asked to fix1328conflicts manually, just as in the case of <<resolving-a-merge,1329resolving a merge>>.13301331Fixing a mistake by editing history1332~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~13331334If the problematic commit is the most recent commit, and you have not1335yet made that commit public, then you may just1336<<undoing-a-merge,destroy it using git-reset>>.13371338Alternatively, you1339can edit the working directory and update the index to fix your1340mistake, just as if you were going to <<how-to-make-a-commit,create a1341new commit>>, then run13421343-------------------------------------------------1344$ git commit --amend1345-------------------------------------------------13461347which will replace the old commit by a new commit incorporating your1348changes, giving you a chance to edit the old commit message first.13491350Again, you should never do this to a commit that may already have1351been merged into another branch; use gitlink:git-revert[1] instead in1352that case.13531354It is also possible to edit commits further back in the history, but1355this is an advanced topic to be left for1356<<cleaning-up-history,another chapter>>.13571358Checking out an old version of a file1359~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~13601361In the process of undoing a previous bad change, you may find it1362useful to check out an older version of a particular file using1363gitlink:git-checkout[1]. We've used git checkout before to switch1364branches, but it has quite different behavior if it is given a path1365name: the command13661367-------------------------------------------------1368$ git checkout HEAD^ path/to/file1369-------------------------------------------------13701371replaces path/to/file by the contents it had in the commit HEAD^, and1372also updates the index to match. It does not change branches.13731374If you just want to look at an old version of the file, without1375modifying the working directory, you can do that with1376gitlink:git-show[1]:13771378-------------------------------------------------1379$ git show HEAD^ path/to/file1380-------------------------------------------------13811382which will display the given version of the file.13831384Ensuring good performance1385-------------------------13861387On large repositories, git depends on compression to keep the history1388information from taking up to much space on disk or in memory.13891390This compression is not performed automatically. Therefore you1391should occasionally run gitlink:git-gc[1]:13921393-------------------------------------------------1394$ git gc1395-------------------------------------------------13961397to recompress the archive. This can be very time-consuming, so1398you may prefer to run git-gc when you are not doing other work.13991400Ensuring reliability1401--------------------14021403Checking the repository for corruption1404~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~14051406The gitlink:git-fsck[1] command runs a number of self-consistency checks1407on the repository, and reports on any problems. This may take some1408time. The most common warning by far is about "dangling" objects:14091410-------------------------------------------------1411$ git fsck1412dangling commit 7281251ddd2a61e38657c827739c57015671a6b31413dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a631414dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b51415dangling blob 218761f9d90712d37a9c5e36f406f92202db07eb1416dangling commit bf093535a34a4d35731aa2bd90fe6b176302f14f1417dangling commit 8e4bec7f2ddaa268bef999853c25755452100f8e1418dangling tree d50bb86186bf27b681d25af89d3b5b68382e40851419dangling tree b24c2473f1fd3d91352a624795be026d64c8841f1420...1421-------------------------------------------------14221423Dangling objects are objects that are harmless, but also unnecessary;1424you can remove them at any time with gitlink:git-prune[1] or the --prune1425option to gitlink:git-gc[1]:14261427-------------------------------------------------1428$ git gc --prune1429-------------------------------------------------14301431This may be time-consuming. Unlike most other git operations (including1432git-gc when run without any options), it is not safe to prune while1433other git operations are in progress in the same repository.14341435For more about dangling objects, see <<dangling-objects>>.143614371438Recovering lost changes1439~~~~~~~~~~~~~~~~~~~~~~~14401441Reflogs1442^^^^^^^14431444Say you modify a branch with gitlink:git-reset[1] --hard, and then1445realize that the branch was the only reference you had to that point in1446history.14471448Fortunately, git also keeps a log, called a "reflog", of all the1449previous values of each branch. So in this case you can still find the1450old history using, for example, 14511452-------------------------------------------------1453$ git log master@{1}1454-------------------------------------------------14551456This lists the commits reachable from the previous version of the head.1457This syntax can be used to with any git command that accepts a commit,1458not just with git log. Some other examples:14591460-------------------------------------------------1461$ git show master@{2} # See where the branch pointed 2,1462$ git show master@{3} # 3, ... changes ago.1463$ gitk master@{yesterday} # See where it pointed yesterday,1464$ gitk master@{"1 week ago"} # ... or last week1465-------------------------------------------------14661467The reflogs are kept by default for 30 days, after which they may be1468pruned. See gitlink:git-reflink[1] and gitlink:git-gc[1] to learn1469how to control this pruning, and see the "SPECIFYING REVISIONS"1470section of gitlink:git-rev-parse[1] for details.14711472Note that the reflog history is very different from normal git history.1473While normal history is shared by every repository that works on the1474same project, the reflog history is not shared: it tells you only about1475how the branches in your local repository have changed over time.14761477Examining dangling objects1478^^^^^^^^^^^^^^^^^^^^^^^^^^14791480In some situations the reflog may not be able to save you. For1481example, suppose you delete a branch, then realize you need the history1482it pointed you. The reflog is also deleted; however, if you have not1483yet pruned the repository, then you may still be able to find1484the lost commits; run git-fsck and watch for output that mentions1485"dangling commits":14861487-------------------------------------------------1488$ git fsck1489dangling commit 7281251ddd2a61e38657c827739c57015671a6b31490dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a631491dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b51492...1493-------------------------------------------------14941495and watch for output that mentions "dangling commits". You can examine1496one of those dangling commits with, for example,14971498------------------------------------------------1499$ gitk 7281251ddd --not --all1500------------------------------------------------15011502which does what it sounds like: it says that you want to see the commit1503history that is described by the dangling commit(s), but not the1504history that is described by all your existing branches and tags. Thus1505you get exactly the history reachable from that commit that is lost.1506(And notice that it might not be just one commit: we only report the1507"tip of the line" as being dangling, but there might be a whole deep1508and complex commit history that was gotten dropped.)15091510If you decide you want the history back, you can always create a new1511reference pointing to it, for example, a new branch:15121513------------------------------------------------1514$ git branch recovered-branch 7281251ddd 1515------------------------------------------------151615171518Sharing development with others1519===============================15201521[[getting-updates-with-git-pull]]1522Getting updates with git pull1523-----------------------------15241525After you clone a repository and make a few changes of your own, you1526may wish to check the original repository for updates and merge them1527into your own work.15281529We have already seen <<Updating-a-repository-with-git-fetch,how to1530keep remote tracking branches up to date>> with gitlink:git-fetch[1],1531and how to merge two branches. So you can merge in changes from the1532original repository's master branch with:15331534-------------------------------------------------1535$ git fetch1536$ git merge origin/master1537-------------------------------------------------15381539However, the gitlink:git-pull[1] command provides a way to do this in1540one step:15411542-------------------------------------------------1543$ git pull origin master1544-------------------------------------------------15451546In fact, "origin" is normally the default repository to pull from,1547and the default branch is normally the HEAD of the remote repository,1548so often you can accomplish the above with just15491550-------------------------------------------------1551$ git pull1552-------------------------------------------------15531554See the descriptions of the branch.<name>.remote and1555branch.<name>.merge options in gitlink:git-config[1] to learn1556how to control these defaults depending on the current branch.15571558In addition to saving you keystrokes, "git pull" also helps you by1559producing a default commit message documenting the branch and1560repository that you pulled from.15611562(But note that no such commit will be created in the case of a1563<<fast-forwards,fast forward>>; instead, your branch will just be1564updated to point to the latest commit from the upstream branch).15651566The git-pull command can also be given "." as the "remote" repository,1567in which case it just merges in a branch from the current repository; so1568the commands15691570-------------------------------------------------1571$ git pull . branch1572$ git merge branch1573-------------------------------------------------15741575are roughly equivalent. The former is actually very commonly used.15761577Submitting patches to a project1578-------------------------------15791580If you just have a few changes, the simplest way to submit them may1581just be to send them as patches in email:15821583First, use gitlink:git-format-patches[1]; for example:15841585-------------------------------------------------1586$ git format-patch origin1587-------------------------------------------------15881589will produce a numbered series of files in the current directory, one1590for each patch in the current branch but not in origin/HEAD.15911592You can then import these into your mail client and send them by1593hand. However, if you have a lot to send at once, you may prefer to1594use the gitlink:git-send-email[1] script to automate the process.1595Consult the mailing list for your project first to determine how they1596prefer such patches be handled.15971598Importing patches to a project1599------------------------------16001601Git also provides a tool called gitlink:git-am[1] (am stands for1602"apply mailbox"), for importing such an emailed series of patches.1603Just save all of the patch-containing messages, in order, into a1604single mailbox file, say "patches.mbox", then run16051606-------------------------------------------------1607$ git am -3 patches.mbox1608-------------------------------------------------16091610Git will apply each patch in order; if any conflicts are found, it1611will stop, and you can fix the conflicts as described in1612"<<resolving-a-merge,Resolving a merge>>". (The "-3" option tells1613git to perform a merge; if you would prefer it just to abort and1614leave your tree and index untouched, you may omit that option.)16151616Once the index is updated with the results of the conflict1617resolution, instead of creating a new commit, just run16181619-------------------------------------------------1620$ git am --resolved1621-------------------------------------------------16221623and git will create the commit for you and continue applying the1624remaining patches from the mailbox.16251626The final result will be a series of commits, one for each patch in1627the original mailbox, with authorship and commit log message each1628taken from the message containing each patch.16291630[[setting-up-a-public-repository]]1631Setting up a public repository1632------------------------------16331634Another way to submit changes to a project is to simply tell the1635maintainer of that project to pull from your repository, exactly as1636you did in the section "<<getting-updates-with-git-pull, Getting1637updates with git pull>>".16381639If you and maintainer both have accounts on the same machine, then1640then you can just pull changes from each other's repositories1641directly; note that all of the command (gitlink:git-clone[1],1642git-fetch[1], git-pull[1], etc.) which accept a URL as an argument1643will also accept a local file patch; so, for example, you can1644use16451646-------------------------------------------------1647$ git clone /path/to/repository1648$ git pull /path/to/other/repository1649-------------------------------------------------16501651If this sort of setup is inconvenient or impossible, another (more1652common) option is to set up a public repository on a public server.1653This also allows you to cleanly separate private work in progress1654from publicly visible work.16551656You will continue to do your day-to-day work in your personal1657repository, but periodically "push" changes from your personal1658repository into your public repository, allowing other developers to1659pull from that repository. So the flow of changes, in a situation1660where there is one other developer with a public repository, looks1661like this:16621663 you push1664 your personal repo ------------------> your public repo1665 ^ |1666 | |1667 | you pull | they pull1668 | |1669 | |1670 | they push V1671 their public repo <------------------- their repo16721673Now, assume your personal repository is in the directory ~/proj. We1674first create a new clone of the repository:16751676-------------------------------------------------1677$ git clone --bare proj-clone.git1678-------------------------------------------------16791680The resulting directory proj-clone.git will contains a "bare" git1681repository--it is just the contents of the ".git" directory, without1682a checked-out copy of a working directory.16831684Next, copy proj-clone.git to the server where you plan to host the1685public repository. You can use scp, rsync, or whatever is most1686convenient.16871688If somebody else maintains the public server, they may already have1689set up a git service for you, and you may skip to the section1690"<<pushing-changes-to-a-public-repository,Pushing changes to a public1691repository>>", below.16921693Otherwise, the following sections explain how to export your newly1694created public repository:16951696[[exporting-via-http]]1697Exporting a git repository via http1698-----------------------------------16991700The git protocol gives better performance and reliability, but on a1701host with a web server set up, http exports may be simpler to set up.17021703All you need to do is place the newly created bare git repository in1704a directory that is exported by the web server, and make some1705adjustments to give web clients some extra information they need:17061707-------------------------------------------------1708$ mv proj.git /home/you/public_html/proj.git1709$ cd proj.git1710$ git update-server-info1711$ chmod a+x hooks/post-update1712-------------------------------------------------17131714(For an explanation of the last two lines, see1715gitlink:git-update-server-info[1], and the documentation1716link:hooks.txt[Hooks used by git].)17171718Advertise the url of proj.git. Anybody else should then be able to1719clone or pull from that url, for example with a commandline like:17201721-------------------------------------------------1722$ git clone http://yourserver.com/~you/proj.git1723-------------------------------------------------17241725(See also1726link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]1727for a slightly more sophisticated setup using WebDAV which also1728allows pushing over http.)17291730[[exporting-via-git]]1731Exporting a git repository via the git protocol1732-----------------------------------------------17331734This is the preferred method.17351736For now, we refer you to the gitlink:git-daemon[1] man page for1737instructions. (See especially the examples section.)17381739[[pushing-changes-to-a-public-repository]]1740Pushing changes to a public repository1741--------------------------------------17421743Note that the two techniques outline above (exporting via1744<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other1745maintainers to fetch your latest changes, but they do not allow write1746access, which you will need to update the public repository with the1747latest changes created in your private repository.17481749The simplest way to do this is using gitlink:git-push[1] and ssh; to1750update the remote branch named "master" with the latest state of your1751branch named "master", run17521753-------------------------------------------------1754$ git push ssh://yourserver.com/~you/proj.git master:master1755-------------------------------------------------17561757or just17581759-------------------------------------------------1760$ git push ssh://yourserver.com/~you/proj.git master1761-------------------------------------------------17621763As with git-fetch, git-push will complain if this does not result in1764a <<fast-forwards,fast forward>>. Normally this is a sign of1765something wrong. However, if you are sure you know what you're1766doing, you may force git-push to perform the update anyway by1767proceeding the branch name by a plus sign:17681769-------------------------------------------------1770$ git push ssh://yourserver.com/~you/proj.git +master1771-------------------------------------------------17721773As with git-fetch, you may also set up configuration options to1774save typing; so, for example, after17751776-------------------------------------------------1777$ cat >.git/config <<EOF1778[remote "public-repo"]1779 url = ssh://yourserver.com/~you/proj.git1780EOF1781-------------------------------------------------17821783you should be able to perform the above push with just17841785-------------------------------------------------1786$ git push public-repo master1787-------------------------------------------------17881789See the explanations of the remote.<name>.url, branch.<name>.remote,1790and remote.<name>.push options in gitlink:git-config[1] for1791details.17921793Setting up a shared repository1794------------------------------17951796Another way to collaborate is by using a model similar to that1797commonly used in CVS, where several developers with special rights1798all push to and pull from a single shared repository. See1799link:cvs-migration.txt[git for CVS users] for instructions on how to1800set this up.18011802Allow web browsing of a repository1803----------------------------------18041805TODO: Brief setup-instructions for gitweb18061807Examples1808--------18091810TODO: topic branches, typical roles as in everyday.txt, ?181118121813[[cleaning-up-history]]1814Rewriting history and maintaining patch series1815==============================================18161817Normally commits are only added to a project, never taken away or1818replaced. Git is designed with this assumption, and violating it will1819cause git's merge machinery (for example) to do the wrong thing.18201821However, there is a situation in which it can be useful to violate this1822assumption.18231824Creating the perfect patch series1825---------------------------------18261827Suppose you are a contributor to a large project, and you want to add a1828complicated feature, and to present it to the other developers in a way1829that makes it easy for them to read your changes, verify that they are1830correct, and understand why you made each change.18311832If you present all of your changes as a single patch (or commit), they1833may find it is too much to digest all at once.18341835If you present them with the entire history of your work, complete with1836mistakes, corrections, and dead ends, they may be overwhelmed.18371838So the ideal is usually to produce a series of patches such that:18391840 1. Each patch can be applied in order.18411842 2. Each patch includes a single logical change, together with a1843 message explaining the change.18441845 3. No patch introduces a regression: after applying any initial1846 part of the series, the resulting project still compiles and1847 works, and has no bugs that it didn't have before.18481849 4. The complete series produces the same end result as your own1850 (probably much messier!) development process did.18511852We will introduce some tools that can help you do this, explain how to1853use them, and then explain some of the problems that can arise because1854you are rewriting history.18551856Keeping a patch series up to date using git-rebase1857--------------------------------------------------18581859Suppose you have a series of commits in a branch "mywork", which1860originally branched off from "origin".18611862Suppose you create a branch "mywork" on a remote-tracking branch1863"origin", and created some commits on top of it:18641865-------------------------------------------------1866$ git checkout -b mywork origin1867$ vi file.txt1868$ git commit1869$ vi otherfile.txt1870$ git commit1871...1872-------------------------------------------------18731874You have performed no merges into mywork, so it is just a simple linear1875sequence of patches on top of "origin":187618771878 o--o--o <-- origin1879 \1880 o--o--o <-- mywork18811882Some more interesting work has been done in the upstream project, and1883"origin" has advanced:18841885 o--o--O--o--o--o <-- origin1886 \1887 a--b--c <-- mywork18881889At this point, you could use "pull" to merge your changes back in;1890the result would create a new merge commit, like this:189118921893 o--o--O--o--o--o <-- origin1894 \ \1895 a--b--c--m <-- mywork18961897However, if you prefer to keep the history in mywork a simple series of1898commits without any merges, you may instead choose to use1899gitlink:git-rebase[1]:19001901-------------------------------------------------1902$ git checkout mywork1903$ git rebase origin1904-------------------------------------------------19051906This will remove each of your commits from mywork, temporarily saving1907them as patches (in a directory named ".dotest"), update mywork to1908point at the latest version of origin, then apply each of the saved1909patches to the new mywork. The result will look like:191019111912 o--o--O--o--o--o <-- origin1913 \1914 a'--b'--c' <-- mywork19151916In the process, it may discover conflicts. In that case it will stop1917and allow you to fix the conflicts; after fixing conflicts, use "git1918add" to update the index with those contents, and then, instead of1919running git-commit, just run19201921-------------------------------------------------1922$ git rebase --continue1923-------------------------------------------------19241925and git will continue applying the rest of the patches.19261927At any point you may use the --abort option to abort this process and1928return mywork to the state it had before you started the rebase:19291930-------------------------------------------------1931$ git rebase --abort1932-------------------------------------------------19331934Reordering or selecting from a patch series1935-------------------------------------------19361937Given one existing commit, the gitlink:git-cherry-pick[1] command1938allows you to apply the change introduced by that commit and create a1939new commit that records it. So, for example, if "mywork" points to a1940series of patches on top of "origin", you might do something like:19411942-------------------------------------------------1943$ git checkout -b mywork-new origin1944$ gitk origin..mywork &1945-------------------------------------------------19461947And browse through the list of patches in the mywork branch using gitk,1948applying them (possibly in a different order) to mywork-new using1949cherry-pick, and possibly modifying them as you go using commit1950--amend.19511952Another technique is to use git-format-patch to create a series of1953patches, then reset the state to before the patches:19541955-------------------------------------------------1956$ git format-patch origin1957$ git reset --hard origin1958-------------------------------------------------19591960Then modify, reorder, or eliminate patches as preferred before applying1961them again with gitlink:git-am[1].19621963Other tools1964-----------19651966There are numerous other tools, such as stgit, which exist for the1967purpose of maintaining a patch series. These are out of the scope of1968this manual.19691970Problems with rewriting history1971-------------------------------19721973The primary problem with rewriting the history of a branch has to do1974with merging. Suppose somebody fetches your branch and merges it into1975their branch, with a result something like this:19761977 o--o--O--o--o--o <-- origin1978 \ \1979 t--t--t--m <-- their branch:19801981Then suppose you modify the last three commits:19821983 o--o--o <-- new head of origin1984 /1985 o--o--O--o--o--o <-- old head of origin19861987If we examined all this history together in one repository, it will1988look like:19891990 o--o--o <-- new head of origin1991 /1992 o--o--O--o--o--o <-- old head of origin1993 \ \1994 t--t--t--m <-- their branch:19951996Git has no way of knowing that the new head is an updated version of1997the old head; it treats this situation exactly the same as it would if1998two developers had independently done the work on the old and new heads1999in parallel. At this point, if someone attempts to merge the new head2000in to their branch, git will attempt to merge together the two (old and2001new) lines of development, instead of trying to replace the old by the2002new. The results are likely to be unexpected.20032004You may still choose to publish branches whose history is rewritten,2005and it may be useful for others to be able to fetch those branches in2006order to examine or test them, but they should not attempt to pull such2007branches into their own work.20082009For true distributed development that supports proper merging,2010published branches should never be rewritten.20112012Advanced branch management2013==========================20142015Fetching individual branches2016----------------------------20172018Instead of using gitlink:git-remote[1], you can also choose just2019to update one branch at a time, and to store it locally under an2020arbitrary name:20212022-------------------------------------------------2023$ git fetch origin todo:my-todo-work2024-------------------------------------------------20252026The first argument, "origin", just tells git to fetch from the2027repository you originally cloned from. The second argument tells git2028to fetch the branch named "todo" from the remote repository, and to2029store it locally under the name refs/heads/my-todo-work.20302031You can also fetch branches from other repositories; so20322033-------------------------------------------------2034$ git fetch git://example.com/proj.git master:example-master2035-------------------------------------------------20362037will create a new branch named "example-master" and store in it the2038branch named "master" from the repository at the given URL. If you2039already have a branch named example-master, it will attempt to2040"fast-forward" to the commit given by example.com's master branch. So2041next we explain what a fast-forward is:20422043[[fast-forwards]]2044Understanding git history: fast-forwards2045----------------------------------------20462047In the previous example, when updating an existing branch, "git2048fetch" checks to make sure that the most recent commit on the remote2049branch is a descendant of the most recent commit on your copy of the2050branch before updating your copy of the branch to point at the new2051commit. Git calls this process a "fast forward".20522053A fast forward looks something like this:20542055 o--o--o--o <-- old head of the branch2056 \2057 o--o--o <-- new head of the branch205820592060In some cases it is possible that the new head will *not* actually be2061a descendant of the old head. For example, the developer may have2062realized she made a serious mistake, and decided to backtrack,2063resulting in a situation like:20642065 o--o--o--o--a--b <-- old head of the branch2066 \2067 o--o--o <-- new head of the branch2068206920702071In this case, "git fetch" will fail, and print out a warning.20722073In that case, you can still force git to update to the new head, as2074described in the following section. However, note that in the2075situation above this may mean losing the commits labeled "a" and "b",2076unless you've already created a reference of your own pointing to2077them.20782079Forcing git fetch to do non-fast-forward updates2080------------------------------------------------20812082If git fetch fails because the new head of a branch is not a2083descendant of the old head, you may force the update with:20842085-------------------------------------------------2086$ git fetch git://example.com/proj.git +master:refs/remotes/example/master2087-------------------------------------------------20882089Note the addition of the "+" sign. Be aware that commits which the2090old version of example/master pointed at may be lost, as we saw in2091the previous section.20922093Configuring remote branches2094---------------------------20952096We saw above that "origin" is just a shortcut to refer to the2097repository which you originally cloned from. This information is2098stored in git configuration variables, which you can see using2099gitlink:git-config[1]:21002101-------------------------------------------------2102$ git config -l2103core.repositoryformatversion=02104core.filemode=true2105core.logallrefupdates=true2106remote.origin.url=git://git.kernel.org/pub/scm/git/git.git2107remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*2108branch.master.remote=origin2109branch.master.merge=refs/heads/master2110-------------------------------------------------21112112If there are other repositories that you also use frequently, you can2113create similar configuration options to save typing; for example,2114after21152116-------------------------------------------------2117$ git config remote.example.url git://example.com/proj.git2118-------------------------------------------------21192120then the following two commands will do the same thing:21212122-------------------------------------------------2123$ git fetch git://example.com/proj.git master:refs/remotes/example/master2124$ git fetch example master:refs/remotes/example/master2125-------------------------------------------------21262127Even better, if you add one more option:21282129-------------------------------------------------2130$ git config remote.example.fetch master:refs/remotes/example/master2131-------------------------------------------------21322133then the following commands will all do the same thing:21342135-------------------------------------------------2136$ git fetch git://example.com/proj.git master:ref/remotes/example/master2137$ git fetch example master:ref/remotes/example/master2138$ git fetch example example/master2139$ git fetch example2140-------------------------------------------------21412142You can also add a "+" to force the update each time:21432144-------------------------------------------------2145$ git config remote.example.fetch +master:ref/remotes/example/master2146-------------------------------------------------21472148Don't do this unless you're sure you won't mind "git fetch" possibly2149throwing away commits on mybranch.21502151Also note that all of the above configuration can be performed by2152directly editing the file .git/config instead of using2153gitlink:git-config[1].21542155See gitlink:git-config[1] for more details on the configuration2156options mentioned above.215721582159Git internals2160=============21612162There are two object abstractions: the "object database", and the2163"current directory cache" aka "index".21642165The Object Database2166-------------------21672168The object database is literally just a content-addressable collection2169of objects. All objects are named by their content, which is2170approximated by the SHA1 hash of the object itself. Objects may refer2171to other objects (by referencing their SHA1 hash), and so you can2172build up a hierarchy of objects.21732174All objects have a statically determined "type" aka "tag", which is2175determined at object creation time, and which identifies the format of2176the object (i.e. how it is used, and how it can refer to other2177objects). There are currently four different object types: "blob",2178"tree", "commit" and "tag".21792180A "blob" object cannot refer to any other object, and is, like the type2181implies, a pure storage object containing some user data. It is used to2182actually store the file data, i.e. a blob object is associated with some2183particular version of some file. 21842185A "tree" object is an object that ties one or more "blob" objects into a2186directory structure. In addition, a tree object can refer to other tree2187objects, thus creating a directory hierarchy. 21882189A "commit" object ties such directory hierarchies together into2190a DAG of revisions - each "commit" is associated with exactly one tree2191(the directory hierarchy at the time of the commit). In addition, a2192"commit" refers to one or more "parent" commit objects that describe the2193history of how we arrived at that directory hierarchy.21942195As a special case, a commit object with no parents is called the "root"2196object, and is the point of an initial project commit. Each project2197must have at least one root, and while you can tie several different2198root objects together into one project by creating a commit object which2199has two or more separate roots as its ultimate parents, that's probably2200just going to confuse people. So aim for the notion of "one root object2201per project", even if git itself does not enforce that. 22022203A "tag" object symbolically identifies and can be used to sign other2204objects. It contains the identifier and type of another object, a2205symbolic name (of course!) and, optionally, a signature.22062207Regardless of object type, all objects share the following2208characteristics: they are all deflated with zlib, and have a header2209that not only specifies their type, but also provides size information2210about the data in the object. It's worth noting that the SHA1 hash2211that is used to name the object is the hash of the original data2212plus this header, so `sha1sum` 'file' does not match the object name2213for 'file'.2214(Historical note: in the dawn of the age of git the hash2215was the sha1 of the 'compressed' object.)22162217As a result, the general consistency of an object can always be tested2218independently of the contents or the type of the object: all objects can2219be validated by verifying that (a) their hashes match the content of the2220file and (b) the object successfully inflates to a stream of bytes that2221forms a sequence of <ascii type without space> + <space> + <ascii decimal2222size> + <byte\0> + <binary object data>. 22232224The structured objects can further have their structure and2225connectivity to other objects verified. This is generally done with2226the `git-fsck` program, which generates a full dependency graph2227of all objects, and verifies their internal consistency (in addition2228to just verifying their superficial consistency through the hash).22292230The object types in some more detail:22312232Blob Object2233-----------22342235A "blob" object is nothing but a binary blob of data, and doesn't2236refer to anything else. There is no signature or any other2237verification of the data, so while the object is consistent (it 'is'2238indexed by its sha1 hash, so the data itself is certainly correct), it2239has absolutely no other attributes. No name associations, no2240permissions. It is purely a blob of data (i.e. normally "file2241contents").22422243In particular, since the blob is entirely defined by its data, if two2244files in a directory tree (or in multiple different versions of the2245repository) have the same contents, they will share the same blob2246object. The object is totally independent of its location in the2247directory tree, and renaming a file does not change the object that2248file is associated with in any way.22492250A blob is typically created when gitlink:git-update-index[1]2251is run, and its data can be accessed by gitlink:git-cat-file[1].22522253Tree Object2254-----------22552256The next hierarchical object type is the "tree" object. A tree object2257is a list of mode/name/blob data, sorted by name. Alternatively, the2258mode data may specify a directory mode, in which case instead of2259naming a blob, that name is associated with another TREE object.22602261Like the "blob" object, a tree object is uniquely determined by the2262set contents, and so two separate but identical trees will always2263share the exact same object. This is true at all levels, i.e. it's2264true for a "leaf" tree (which does not refer to any other trees, only2265blobs) as well as for a whole subdirectory.22662267For that reason a "tree" object is just a pure data abstraction: it2268has no history, no signatures, no verification of validity, except2269that since the contents are again protected by the hash itself, we can2270trust that the tree is immutable and its contents never change.22712272So you can trust the contents of a tree to be valid, the same way you2273can trust the contents of a blob, but you don't know where those2274contents 'came' from.22752276Side note on trees: since a "tree" object is a sorted list of2277"filename+content", you can create a diff between two trees without2278actually having to unpack two trees. Just ignore all common parts,2279and your diff will look right. In other words, you can effectively2280(and efficiently) tell the difference between any two random trees by2281O(n) where "n" is the size of the difference, rather than the size of2282the tree.22832284Side note 2 on trees: since the name of a "blob" depends entirely and2285exclusively on its contents (i.e. there are no names or permissions2286involved), you can see trivial renames or permission changes by2287noticing that the blob stayed the same. However, renames with data2288changes need a smarter "diff" implementation.22892290A tree is created with gitlink:git-write-tree[1] and2291its data can be accessed by gitlink:git-ls-tree[1].2292Two trees can be compared with gitlink:git-diff-tree[1].22932294Commit Object2295-------------22962297The "commit" object is an object that introduces the notion of2298history into the picture. In contrast to the other objects, it2299doesn't just describe the physical state of a tree, it describes how2300we got there, and why.23012302A "commit" is defined by the tree-object that it results in, the2303parent commits (zero, one or more) that led up to that point, and a2304comment on what happened. Again, a commit is not trusted per se:2305the contents are well-defined and "safe" due to the cryptographically2306strong signatures at all levels, but there is no reason to believe2307that the tree is "good" or that the merge information makes sense.2308The parents do not have to actually have any relationship with the2309result, for example.23102311Note on commits: unlike real SCM's, commits do not contain2312rename information or file mode change information. All of that is2313implicit in the trees involved (the result tree, and the result trees2314of the parents), and describing that makes no sense in this idiotic2315file manager.23162317A commit is created with gitlink:git-commit-tree[1] and2318its data can be accessed by gitlink:git-cat-file[1].23192320Trust2321-----23222323An aside on the notion of "trust". Trust is really outside the scope2324of "git", but it's worth noting a few things. First off, since2325everything is hashed with SHA1, you 'can' trust that an object is2326intact and has not been messed with by external sources. So the name2327of an object uniquely identifies a known state - just not a state that2328you may want to trust.23292330Furthermore, since the SHA1 signature of a commit refers to the2331SHA1 signatures of the tree it is associated with and the signatures2332of the parent, a single named commit specifies uniquely a whole set2333of history, with full contents. You can't later fake any step of the2334way once you have the name of a commit.23352336So to introduce some real trust in the system, the only thing you need2337to do is to digitally sign just 'one' special note, which includes the2338name of a top-level commit. Your digital signature shows others2339that you trust that commit, and the immutability of the history of2340commits tells others that they can trust the whole history.23412342In other words, you can easily validate a whole archive by just2343sending out a single email that tells the people the name (SHA1 hash)2344of the top commit, and digitally sign that email using something2345like GPG/PGP.23462347To assist in this, git also provides the tag object...23482349Tag Object2350----------23512352Git provides the "tag" object to simplify creating, managing and2353exchanging symbolic and signed tokens. The "tag" object at its2354simplest simply symbolically identifies another object by containing2355the sha1, type and symbolic name.23562357However it can optionally contain additional signature information2358(which git doesn't care about as long as there's less than 8k of2359it). This can then be verified externally to git.23602361Note that despite the tag features, "git" itself only handles content2362integrity; the trust framework (and signature provision and2363verification) has to come from outside.23642365A tag is created with gitlink:git-mktag[1],2366its data can be accessed by gitlink:git-cat-file[1],2367and the signature can be verified by2368gitlink:git-verify-tag[1].236923702371The "index" aka "Current Directory Cache"2372-----------------------------------------23732374The index is a simple binary file, which contains an efficient2375representation of a virtual directory content at some random time. It2376does so by a simple array that associates a set of names, dates,2377permissions and content (aka "blob") objects together. The cache is2378always kept ordered by name, and names are unique (with a few very2379specific rules) at any point in time, but the cache has no long-term2380meaning, and can be partially updated at any time.23812382In particular, the index certainly does not need to be consistent with2383the current directory contents (in fact, most operations will depend on2384different ways to make the index 'not' be consistent with the directory2385hierarchy), but it has three very important attributes:23862387'(a) it can re-generate the full state it caches (not just the2388directory structure: it contains pointers to the "blob" objects so2389that it can regenerate the data too)'23902391As a special case, there is a clear and unambiguous one-way mapping2392from a current directory cache to a "tree object", which can be2393efficiently created from just the current directory cache without2394actually looking at any other data. So a directory cache at any one2395time uniquely specifies one and only one "tree" object (but has2396additional data to make it easy to match up that tree object with what2397has happened in the directory)23982399'(b) it has efficient methods for finding inconsistencies between that2400cached state ("tree object waiting to be instantiated") and the2401current state.'24022403'(c) it can additionally efficiently represent information about merge2404conflicts between different tree objects, allowing each pathname to be2405associated with sufficient information about the trees involved that2406you can create a three-way merge between them.'24072408Those are the three ONLY things that the directory cache does. It's a2409cache, and the normal operation is to re-generate it completely from a2410known tree object, or update/compare it with a live tree that is being2411developed. If you blow the directory cache away entirely, you generally2412haven't lost any information as long as you have the name of the tree2413that it described. 24142415At the same time, the index is at the same time also the2416staging area for creating new trees, and creating a new tree always2417involves a controlled modification of the index file. In particular,2418the index file can have the representation of an intermediate tree that2419has not yet been instantiated. So the index can be thought of as a2420write-back cache, which can contain dirty information that has not yet2421been written back to the backing store.2422242324242425The Workflow2426------------24272428Generally, all "git" operations work on the index file. Some operations2429work *purely* on the index file (showing the current state of the2430index), but most operations move data to and from the index file. Either2431from the database or from the working directory. Thus there are four2432main combinations: 24332434working directory -> index2435~~~~~~~~~~~~~~~~~~~~~~~~~~24362437You update the index with information from the working directory with2438the gitlink:git-update-index[1] command. You2439generally update the index information by just specifying the filename2440you want to update, like so:24412442-------------------------------------------------2443$ git-update-index filename2444-------------------------------------------------24452446but to avoid common mistakes with filename globbing etc, the command2447will not normally add totally new entries or remove old entries,2448i.e. it will normally just update existing cache entries.24492450To tell git that yes, you really do realize that certain files no2451longer exist, or that new files should be added, you2452should use the `--remove` and `--add` flags respectively.24532454NOTE! A `--remove` flag does 'not' mean that subsequent filenames will2455necessarily be removed: if the files still exist in your directory2456structure, the index will be updated with their new status, not2457removed. The only thing `--remove` means is that update-cache will be2458considering a removed file to be a valid thing, and if the file really2459does not exist any more, it will update the index accordingly.24602461As a special case, you can also do `git-update-index --refresh`, which2462will refresh the "stat" information of each index to match the current2463stat information. It will 'not' update the object status itself, and2464it will only update the fields that are used to quickly test whether2465an object still matches its old backing store object.24662467index -> object database2468~~~~~~~~~~~~~~~~~~~~~~~~24692470You write your current index file to a "tree" object with the program24712472-------------------------------------------------2473$ git-write-tree2474-------------------------------------------------24752476that doesn't come with any options - it will just write out the2477current index into the set of tree objects that describe that state,2478and it will return the name of the resulting top-level tree. You can2479use that tree to re-generate the index at any time by going in the2480other direction:24812482object database -> index2483~~~~~~~~~~~~~~~~~~~~~~~~24842485You read a "tree" file from the object database, and use that to2486populate (and overwrite - don't do this if your index contains any2487unsaved state that you might want to restore later!) your current2488index. Normal operation is just24892490-------------------------------------------------2491$ git-read-tree <sha1 of tree>2492-------------------------------------------------24932494and your index file will now be equivalent to the tree that you saved2495earlier. However, that is only your 'index' file: your working2496directory contents have not been modified.24972498index -> working directory2499~~~~~~~~~~~~~~~~~~~~~~~~~~25002501You update your working directory from the index by "checking out"2502files. This is not a very common operation, since normally you'd just2503keep your files updated, and rather than write to your working2504directory, you'd tell the index files about the changes in your2505working directory (i.e. `git-update-index`).25062507However, if you decide to jump to a new version, or check out somebody2508else's version, or just restore a previous tree, you'd populate your2509index file with read-tree, and then you need to check out the result2510with25112512-------------------------------------------------2513$ git-checkout-index filename2514-------------------------------------------------25152516or, if you want to check out all of the index, use `-a`.25172518NOTE! git-checkout-index normally refuses to overwrite old files, so2519if you have an old version of the tree already checked out, you will2520need to use the "-f" flag ('before' the "-a" flag or the filename) to2521'force' the checkout.252225232524Finally, there are a few odds and ends which are not purely moving2525from one representation to the other:25262527Tying it all together2528~~~~~~~~~~~~~~~~~~~~~25292530To commit a tree you have instantiated with "git-write-tree", you'd2531create a "commit" object that refers to that tree and the history2532behind it - most notably the "parent" commits that preceded it in2533history.25342535Normally a "commit" has one parent: the previous state of the tree2536before a certain change was made. However, sometimes it can have two2537or more parent commits, in which case we call it a "merge", due to the2538fact that such a commit brings together ("merges") two or more2539previous states represented by other commits.25402541In other words, while a "tree" represents a particular directory state2542of a working directory, a "commit" represents that state in "time",2543and explains how we got there.25442545You create a commit object by giving it the tree that describes the2546state at the time of the commit, and a list of parents:25472548-------------------------------------------------2549$ git-commit-tree <tree> -p <parent> [-p <parent2> ..]2550-------------------------------------------------25512552and then giving the reason for the commit on stdin (either through2553redirection from a pipe or file, or by just typing it at the tty).25542555git-commit-tree will return the name of the object that represents2556that commit, and you should save it away for later use. Normally,2557you'd commit a new `HEAD` state, and while git doesn't care where you2558save the note about that state, in practice we tend to just write the2559result to the file pointed at by `.git/HEAD`, so that we can always see2560what the last committed state was.25612562Here is an ASCII art by Jon Loeliger that illustrates how2563various pieces fit together.25642565------------25662567 commit-tree2568 commit obj2569 +----+2570 | |2571 | |2572 V V2573 +-----------+2574 | Object DB |2575 | Backing |2576 | Store |2577 +-----------+2578 ^2579 write-tree | |2580 tree obj | |2581 | | read-tree2582 | | tree obj2583 V2584 +-----------+2585 | Index |2586 | "cache" |2587 +-----------+2588 update-index ^2589 blob obj | |2590 | |2591 checkout-index -u | | checkout-index2592 stat | | blob obj2593 V2594 +-----------+2595 | Working |2596 | Directory |2597 +-----------+25982599------------260026012602Examining the data2603------------------26042605You can examine the data represented in the object database and the2606index with various helper tools. For every object, you can use2607gitlink:git-cat-file[1] to examine details about the2608object:26092610-------------------------------------------------2611$ git-cat-file -t <objectname>2612-------------------------------------------------26132614shows the type of the object, and once you have the type (which is2615usually implicit in where you find the object), you can use26162617-------------------------------------------------2618$ git-cat-file blob|tree|commit|tag <objectname>2619-------------------------------------------------26202621to show its contents. NOTE! Trees have binary content, and as a result2622there is a special helper for showing that content, called2623`git-ls-tree`, which turns the binary content into a more easily2624readable form.26252626It's especially instructive to look at "commit" objects, since those2627tend to be small and fairly self-explanatory. In particular, if you2628follow the convention of having the top commit name in `.git/HEAD`,2629you can do26302631-------------------------------------------------2632$ git-cat-file commit HEAD2633-------------------------------------------------26342635to see what the top commit was.26362637Merging multiple trees2638----------------------26392640Git helps you do a three-way merge, which you can expand to n-way by2641repeating the merge procedure arbitrary times until you finally2642"commit" the state. The normal situation is that you'd only do one2643three-way merge (two parents), and commit it, but if you like to, you2644can do multiple parents in one go.26452646To do a three-way merge, you need the two sets of "commit" objects2647that you want to merge, use those to find the closest common parent (a2648third "commit" object), and then use those commit objects to find the2649state of the directory ("tree" object) at these points.26502651To get the "base" for the merge, you first look up the common parent2652of two commits with26532654-------------------------------------------------2655$ git-merge-base <commit1> <commit2>2656-------------------------------------------------26572658which will return you the commit they are both based on. You should2659now look up the "tree" objects of those commits, which you can easily2660do with (for example)26612662-------------------------------------------------2663$ git-cat-file commit <commitname> | head -12664-------------------------------------------------26652666since the tree object information is always the first line in a commit2667object.26682669Once you know the three trees you are going to merge (the one "original"2670tree, aka the common case, and the two "result" trees, aka the branches2671you want to merge), you do a "merge" read into the index. This will2672complain if it has to throw away your old index contents, so you should2673make sure that you've committed those - in fact you would normally2674always do a merge against your last commit (which should thus match what2675you have in your current index anyway).26762677To do the merge, do26782679-------------------------------------------------2680$ git-read-tree -m -u <origtree> <yourtree> <targettree>2681-------------------------------------------------26822683which will do all trivial merge operations for you directly in the2684index file, and you can just write the result out with2685`git-write-tree`.268626872688Merging multiple trees, continued2689---------------------------------26902691Sadly, many merges aren't trivial. If there are files that have2692been added.moved or removed, or if both branches have modified the2693same file, you will be left with an index tree that contains "merge2694entries" in it. Such an index tree can 'NOT' be written out to a tree2695object, and you will have to resolve any such merge clashes using2696other tools before you can write out the result.26972698You can examine such index state with `git-ls-files --unmerged`2699command. An example:27002701------------------------------------------------2702$ git-read-tree -m $orig HEAD $target2703$ git-ls-files --unmerged2704100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello.c2705100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello.c2706100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello.c2707------------------------------------------------27082709Each line of the `git-ls-files --unmerged` output begins with2710the blob mode bits, blob SHA1, 'stage number', and the2711filename. The 'stage number' is git's way to say which tree it2712came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD`2713tree, and stage3 `$target` tree.27142715Earlier we said that trivial merges are done inside2716`git-read-tree -m`. For example, if the file did not change2717from `$orig` to `HEAD` nor `$target`, or if the file changed2718from `$orig` to `HEAD` and `$orig` to `$target` the same way,2719obviously the final outcome is what is in `HEAD`. What the2720above example shows is that file `hello.c` was changed from2721`$orig` to `HEAD` and `$orig` to `$target` in a different way.2722You could resolve this by running your favorite 3-way merge2723program, e.g. `diff3` or `merge`, on the blob objects from2724these three stages yourself, like this:27252726------------------------------------------------2727$ git-cat-file blob 263414f... >hello.c~12728$ git-cat-file blob 06fa6a2... >hello.c~22729$ git-cat-file blob cc44c73... >hello.c~32730$ merge hello.c~2 hello.c~1 hello.c~32731------------------------------------------------27322733This would leave the merge result in `hello.c~2` file, along2734with conflict markers if there are conflicts. After verifying2735the merge result makes sense, you can tell git what the final2736merge result for this file is by:27372738-------------------------------------------------2739$ mv -f hello.c~2 hello.c2740$ git-update-index hello.c2741-------------------------------------------------27422743When a path is in unmerged state, running `git-update-index` for2744that path tells git to mark the path resolved.27452746The above is the description of a git merge at the lowest level,2747to help you understand what conceptually happens under the hood.2748In practice, nobody, not even git itself, uses three `git-cat-file`2749for this. There is `git-merge-index` program that extracts the2750stages to temporary files and calls a "merge" script on it:27512752-------------------------------------------------2753$ git-merge-index git-merge-one-file hello.c2754-------------------------------------------------27552756and that is what higher level `git resolve` is implemented with.27572758How git stores objects efficiently: pack files2759----------------------------------------------27602761We've seen how git stores each object in a file named after the2762object's SHA1 hash.27632764Unfortunately this system becomes inefficient once a project has a2765lot of objects. Try this on an old project:27662767------------------------------------------------2768$ git count-objects27696930 objects, 47620 kilobytes2770------------------------------------------------27712772The first number is the number of objects which are kept in2773individual files. The second is the amount of space taken up by2774those "loose" objects.27752776You can save space and make git faster by moving these loose objects in2777to a "pack file", which stores a group of objects in an efficient2778compressed format; the details of how pack files are formatted can be2779found in link:technical/pack-format.txt[technical/pack-format.txt].27802781To put the loose objects into a pack, just run git repack:27822783------------------------------------------------2784$ git repack2785Generating pack...2786Done counting 6020 objects.2787Deltifying 6020 objects.2788 100% (6020/6020) done2789Writing 6020 objects.2790 100% (6020/6020) done2791Total 6020, written 6020 (delta 4070), reused 0 (delta 0)2792Pack pack-3e54ad29d5b2e05838c75df582c65257b8d08e1c created.2793------------------------------------------------27942795You can then run27962797------------------------------------------------2798$ git prune2799------------------------------------------------28002801to remove any of the "loose" objects that are now contained in the2802pack. This will also remove any unreferenced objects (which may be2803created when, for example, you use "git reset" to remove a commit).2804You can verify that the loose objects are gone by looking at the2805.git/objects directory or by running28062807------------------------------------------------2808$ git count-objects28090 objects, 0 kilobytes2810------------------------------------------------28112812Although the object files are gone, any commands that refer to those2813objects will work exactly as they did before.28142815The gitlink:git-gc[1] command performs packing, pruning, and more for2816you, so is normally the only high-level command you need.28172818[[dangling-objects]]2819Dangling objects2820----------------28212822The gitlink:git-fsck[1] command will sometimes complain about dangling2823objects. They are not a problem.28242825The most common cause of dangling objects is that you've rebased a2826branch, or you have pulled from somebody else who rebased a branch--see2827<<cleaning-up-history>>. In that case, the old head of the original2828branch still exists, as does obviously everything it pointed to. The2829branch pointer itself just doesn't, since you replaced it with another2830one.28312832There are also other situations too that cause dangling objects. For2833example, a "dangling blob" may arise because you did a "git add" of a2834file, but then, before you actually committed it and made it part of the2835bigger picture, you changed something else in that file and committed2836that *updated* thing - the old state that you added originally ends up2837not being pointed to by any commit or tree, so it's now a dangling blob2838object.28392840Similarly, when the "recursive" merge strategy runs, and finds that2841there are criss-cross merges and thus more than one merge base (which is2842fairly unusual, but it does happen), it will generate one temporary2843midway tree (or possibly even more, if you had lots of criss-crossing2844merges and more than two merge bases) as a temporary internal merge2845base, and again, those are real objects, but the end result will not end2846up pointing to them, so they end up "dangling" in your repository.28472848Generally, dangling objects aren't anything to worry about. They can2849even be very useful: if you screw something up, the dangling objects can2850be how you recover your old tree (say, you did a rebase, and realized2851that you really didn't want to - you can look at what dangling objects2852you have, and decide to reset your head to some old dangling state).28532854For commits, the most useful thing to do with dangling objects tends to2855be to do a simple28562857------------------------------------------------2858$ gitk <dangling-commit-sha-goes-here> --not --all2859------------------------------------------------28602861For blobs and trees, you can't do the same, but you can examine them.2862You can just do28632864------------------------------------------------2865$ git show <dangling-blob/tree-sha-goes-here>2866------------------------------------------------28672868to show what the contents of the blob were (or, for a tree, basically2869what the "ls" for that directory was), and that may give you some idea2870of what the operation was that left that dangling object.28712872Usually, dangling blobs and trees aren't very interesting. They're2873almost always the result of either being a half-way mergebase (the blob2874will often even have the conflict markers from a merge in it, if you2875have had conflicting merges that you fixed up by hand), or simply2876because you interrupted a "git fetch" with ^C or something like that,2877leaving _some_ of the new objects in the object database, but just2878dangling and useless.28792880Anyway, once you are sure that you're not interested in any dangling 2881state, you can just prune all unreachable objects:28822883------------------------------------------------2884$ git prune2885------------------------------------------------28862887and they'll be gone. But you should only run "git prune" on a quiescent2888repository - it's kind of like doing a filesystem fsck recovery: you2889don't want to do that while the filesystem is mounted.28902891(The same is true of "git-fsck" itself, btw - but since 2892git-fsck never actually *changes* the repository, it just reports 2893on what it found, git-fsck itself is never "dangerous" to run. 2894Running it while somebody is actually changing the repository can cause 2895confusing and scary messages, but it won't actually do anything bad. In 2896contrast, running "git prune" while somebody is actively changing the 2897repository is a *BAD* idea).28982899Glossary of git terms2900=====================29012902include::glossary.txt[]29032904Notes and todo list for this manual2905===================================29062907This is a work in progress.29082909The basic requirements:2910 - It must be readable in order, from beginning to end, by2911 someone intelligent with a basic grasp of the unix2912 commandline, but without any special knowledge of git. If2913 necessary, any other prerequisites should be specifically2914 mentioned as they arise.2915 - Whenever possible, section headings should clearly describe2916 the task they explain how to do, in language that requires2917 no more knowledge than necessary: for example, "importing2918 patches into a project" rather than "the git-am command"29192920Think about how to create a clear chapter dependency graph that will2921allow people to get to important topics without necessarily reading2922everything in between.29232924Scan Documentation/ for other stuff left out; in particular:2925 howto's2926 some of technical/?2927 hooks2928 etc.29292930Scan email archives for other stuff left out29312932Scan man pages to see if any assume more background than this manual2933provides.29342935Simplify beginning by suggesting disconnected head instead of2936temporary branch creation?29372938Explain how to refer to file stages in the "how to resolve a merge"2939section: diff -1, -2, -3, --ours, --theirs :1:/path notation. The2940"git ls-files --unmerged --stage" thing is sorta useful too,2941actually. And note gitk --merge.29422943Add more good examples. Entire sections of just cookbook examples2944might be a good idea; maybe make an "advanced examples" section a2945standard end-of-chapter section?29462947Include cross-references to the glossary, where appropriate.29482949Document shallow clones? See draft 1.5.0 release notes for some2950documentation.29512952Add a sectin on working with other version control systems, including2953CVS, Subversion, and just imports of series of release tarballs.2954