1Git User's Manual (for version 1.5.3 or newer) 2______________________________________________ 3 4 5Git is a fast distributed revision control system. 6 7This manual is designed to be readable by someone with basic UNIX 8command-line skills, but no previous knowledge of git. 9 10<<repositories-and-branches>> and <<exploring-git-history>> explain how 11to fetch and study a project using git--read these chapters to learn how 12to build and test a particular version of a software project, search for 13regressions, and so on. 14 15People needing to do actual development will also want to read 16<<Developing-with-git>> and <<sharing-development>>. 17 18Further chapters cover more specialized topics. 19 20Comprehensive reference documentation is available through the man 21pages. For a command such as "git clone", just use 22 23------------------------------------------------ 24$ man git-clone 25------------------------------------------------ 26 27See also <<git-quick-start>> for a brief overview of git commands, 28without any explanation. 29 30Finally, see <<todo>> for ways that you can help make this manual more 31complete. 32 33 34[[repositories-and-branches]] 35Repositories and Branches 36========================= 37 38[[how-to-get-a-git-repository]] 39How to get a git repository 40--------------------------- 41 42It will be useful to have a git repository to experiment with as you 43read this manual. 44 45The best way to get one is by using the gitlink:git-clone[1] command to 46download a copy of an existing repository. If you don't already have a 47project in mind, here are some interesting examples: 48 49------------------------------------------------ 50 # git itself (approx. 10MB download): 51$ git clone git://git.kernel.org/pub/scm/git/git.git 52 # the linux kernel (approx. 150MB download): 53$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git 54------------------------------------------------ 55 56The initial clone may be time-consuming for a large project, but you 57will only need to clone once. 58 59The clone command creates a new directory named after the project 60("git" or "linux-2.6" in the examples above). After you cd into this 61directory, you will see that it contains a copy of the project files, 62together with a special top-level directory named ".git", which 63contains all the information about the history of the project. 64 65[[how-to-check-out]] 66How to check out a different version of a project 67------------------------------------------------- 68 69Git is best thought of as a tool for storing the history of a collection 70of files. It stores the history as a compressed collection of 71interrelated snapshots of the project's contents. In git each such 72version is called a <<def_commit,commit>>. 73 74A single git repository may contain multiple branches. It keeps track 75of them by keeping a list of <<def_head,heads>> which reference the 76latest commit on each branch; the gitlink:git-branch[1] command shows 77you the list of branch heads: 78 79------------------------------------------------ 80$ git branch 81* master 82------------------------------------------------ 83 84A freshly cloned repository contains a single branch head, by default 85named "master", with the working directory initialized to the state of 86the project referred to by that branch head. 87 88Most projects also use <<def_tag,tags>>. Tags, like heads, are 89references into the project's history, and can be listed using the 90gitlink:git-tag[1] command: 91 92------------------------------------------------ 93$ git tag -l 94v2.6.11 95v2.6.11-tree 96v2.6.12 97v2.6.12-rc2 98v2.6.12-rc3 99v2.6.12-rc4 100v2.6.12-rc5 101v2.6.12-rc6 102v2.6.13 103... 104------------------------------------------------ 105 106Tags are expected to always point at the same version of a project, 107while heads are expected to advance as development progresses. 108 109Create a new branch head pointing to one of these versions and check it 110out using gitlink:git-checkout[1]: 111 112------------------------------------------------ 113$ git checkout -b new v2.6.13 114------------------------------------------------ 115 116The working directory then reflects the contents that the project had 117when it was tagged v2.6.13, and gitlink:git-branch[1] shows two 118branches, with an asterisk marking the currently checked-out branch: 119 120------------------------------------------------ 121$ git branch 122 master 123* new 124------------------------------------------------ 125 126If you decide that you'd rather see version 2.6.17, you can modify 127the current branch to point at v2.6.17 instead, with 128 129------------------------------------------------ 130$ git reset --hard v2.6.17 131------------------------------------------------ 132 133Note that if the current branch head was your only reference to a 134particular point in history, then resetting that branch may leave you 135with no way to find the history it used to point to; so use this command 136carefully. 137 138[[understanding-commits]] 139Understanding History: Commits 140------------------------------ 141 142Every change in the history of a project is represented by a commit. 143The gitlink:git-show[1] command shows the most recent commit on the 144current branch: 145 146------------------------------------------------ 147$ git show 148commit 17cf781661e6d38f737f15f53ab552f1e95960d7 149Author: Linus Torvalds <torvalds@ppc970.osdl.org.(none)> 150Date: Tue Apr 19 14:11:06 2005 -0700 151 152 Remove duplicate getenv(DB_ENVIRONMENT) call 153 154 Noted by Tony Luck. 155 156diff --git a/init-db.c b/init-db.c 157index 65898fa..b002dc6 100644 158--- a/init-db.c 159+++ b/init-db.c 160@@ -7,7 +7,7 @@ 161 162 int main(int argc, char **argv) 163 { 164- char *sha1_dir = getenv(DB_ENVIRONMENT), *path; 165+ char *sha1_dir, *path; 166 int len, i; 167 168 if (mkdir(".git", 0755) < 0) { 169------------------------------------------------ 170 171As you can see, a commit shows who made the latest change, what they 172did, and why. 173 174Every commit has a 40-hexdigit id, sometimes called the "object name" or the 175"SHA1 id", shown on the first line of the "git show" output. You can usually 176refer to a commit by a shorter name, such as a tag or a branch name, but this 177longer name can also be useful. Most importantly, it is a globally unique 178name for this commit: so if you tell somebody else the object name (for 179example in email), then you are guaranteed that name will refer to the same 180commit in their repository that it does in yours (assuming their repository 181has that commit at all). Since the object name is computed as a hash over the 182contents of the commit, you are guaranteed that the commit can never change 183without its name also changing. 184 185In fact, in <<git-concepts>> we shall see that everything stored in git 186history, including file data and directory contents, is stored in an object 187with a name that is a hash of its contents. 188 189[[understanding-reachability]] 190Understanding history: commits, parents, and reachability 191~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 192 193Every commit (except the very first commit in a project) also has a 194parent commit which shows what happened before this commit. 195Following the chain of parents will eventually take you back to the 196beginning of the project. 197 198However, the commits do not form a simple list; git allows lines of 199development to diverge and then reconverge, and the point where two 200lines of development reconverge is called a "merge". The commit 201representing a merge can therefore have more than one parent, with 202each parent representing the most recent commit on one of the lines 203of development leading to that point. 204 205The best way to see how this works is using the gitlink:gitk[1] 206command; running gitk now on a git repository and looking for merge 207commits will help understand how the git organizes history. 208 209In the following, we say that commit X is "reachable" from commit Y 210if commit X is an ancestor of commit Y. Equivalently, you could say 211that Y is a descendant of X, or that there is a chain of parents 212leading from commit Y to commit X. 213 214[[history-diagrams]] 215Understanding history: History diagrams 216~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 217 218We will sometimes represent git history using diagrams like the one 219below. Commits are shown as "o", and the links between them with 220lines drawn with - / and \. Time goes left to right: 221 222 223................................................ 224 o--o--o <-- Branch A 225 / 226 o--o--o <-- master 227 \ 228 o--o--o <-- Branch B 229................................................ 230 231If we need to talk about a particular commit, the character "o" may 232be replaced with another letter or number. 233 234[[what-is-a-branch]] 235Understanding history: What is a branch? 236~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 237 238When we need to be precise, we will use the word "branch" to mean a line 239of development, and "branch head" (or just "head") to mean a reference 240to the most recent commit on a branch. In the example above, the branch 241head named "A" is a pointer to one particular commit, but we refer to 242the line of three commits leading up to that point as all being part of 243"branch A". 244 245However, when no confusion will result, we often just use the term 246"branch" both for branches and for branch heads. 247 248[[manipulating-branches]] 249Manipulating branches 250--------------------- 251 252Creating, deleting, and modifying branches is quick and easy; here's 253a summary of the commands: 254 255git branch:: 256 list all branches 257git branch <branch>:: 258 create a new branch named <branch>, referencing the same 259 point in history as the current branch 260git branch <branch> <start-point>:: 261 create a new branch named <branch>, referencing 262 <start-point>, which may be specified any way you like, 263 including using a branch name or a tag name 264git branch -d <branch>:: 265 delete the branch <branch>; if the branch you are deleting 266 points to a commit which is not reachable from the current 267 branch, this command will fail with a warning. 268git branch -D <branch>:: 269 even if the branch points to a commit not reachable 270 from the current branch, you may know that that commit 271 is still reachable from some other branch or tag. In that 272 case it is safe to use this command to force git to delete 273 the branch. 274git checkout <branch>:: 275 make the current branch <branch>, updating the working 276 directory to reflect the version referenced by <branch> 277git checkout -b <new> <start-point>:: 278 create a new branch <new> referencing <start-point>, and 279 check it out. 280 281The special symbol "HEAD" can always be used to refer to the current 282branch. In fact, git uses a file named "HEAD" in the .git directory to 283remember which branch is current: 284 285------------------------------------------------ 286$ cat .git/HEAD 287ref: refs/heads/master 288------------------------------------------------ 289 290[[detached-head]] 291Examining an old version without creating a new branch 292------------------------------------------------------ 293 294The git-checkout command normally expects a branch head, but will also 295accept an arbitrary commit; for example, you can check out the commit 296referenced by a tag: 297 298------------------------------------------------ 299$ git checkout v2.6.17 300Note: moving to "v2.6.17" which isn't a local branch 301If you want to create a new branch from this checkout, you may do so 302(now or later) by using -b with the checkout command again. Example: 303 git checkout -b <new_branch_name> 304HEAD is now at 427abfa... Linux v2.6.17 305------------------------------------------------ 306 307The HEAD then refers to the SHA1 of the commit instead of to a branch, 308and git branch shows that you are no longer on a branch: 309 310------------------------------------------------ 311$ cat .git/HEAD 312427abfa28afedffadfca9dd8b067eb6d36bac53f 313$ git branch 314* (no branch) 315 master 316------------------------------------------------ 317 318In this case we say that the HEAD is "detached". 319 320This is an easy way to check out a particular version without having to 321make up a name for the new branch. You can still create a new branch 322(or tag) for this version later if you decide to. 323 324[[examining-remote-branches]] 325Examining branches from a remote repository 326------------------------------------------- 327 328The "master" branch that was created at the time you cloned is a copy 329of the HEAD in the repository that you cloned from. That repository 330may also have had other branches, though, and your local repository 331keeps branches which track each of those remote branches, which you 332can view using the "-r" option to gitlink:git-branch[1]: 333 334------------------------------------------------ 335$ git branch -r 336 origin/HEAD 337 origin/html 338 origin/maint 339 origin/man 340 origin/master 341 origin/next 342 origin/pu 343 origin/todo 344------------------------------------------------ 345 346You cannot check out these remote-tracking branches, but you can 347examine them on a branch of your own, just as you would a tag: 348 349------------------------------------------------ 350$ git checkout -b my-todo-copy origin/todo 351------------------------------------------------ 352 353Note that the name "origin" is just the name that git uses by default 354to refer to the repository that you cloned from. 355 356[[how-git-stores-references]] 357Naming branches, tags, and other references 358------------------------------------------- 359 360Branches, remote-tracking branches, and tags are all references to 361commits. All references are named with a slash-separated path name 362starting with "refs"; the names we've been using so far are actually 363shorthand: 364 365 - The branch "test" is short for "refs/heads/test". 366 - The tag "v2.6.18" is short for "refs/tags/v2.6.18". 367 - "origin/master" is short for "refs/remotes/origin/master". 368 369The full name is occasionally useful if, for example, there ever 370exists a tag and a branch with the same name. 371 372As another useful shortcut, the "HEAD" of a repository can be referred 373to just using the name of that repository. So, for example, "origin" 374is usually a shortcut for the HEAD branch in the repository "origin". 375 376For the complete list of paths which git checks for references, and 377the order it uses to decide which to choose when there are multiple 378references with the same shorthand name, see the "SPECIFYING 379REVISIONS" section of gitlink:git-rev-parse[1]. 380 381[[Updating-a-repository-with-git-fetch]] 382Updating a repository with git fetch 383------------------------------------ 384 385Eventually the developer cloned from will do additional work in her 386repository, creating new commits and advancing the branches to point 387at the new commits. 388 389The command "git fetch", with no arguments, will update all of the 390remote-tracking branches to the latest version found in her 391repository. It will not touch any of your own branches--not even the 392"master" branch that was created for you on clone. 393 394[[fetching-branches]] 395Fetching branches from other repositories 396----------------------------------------- 397 398You can also track branches from repositories other than the one you 399cloned from, using gitlink:git-remote[1]: 400 401------------------------------------------------- 402$ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git 403$ git fetch linux-nfs 404* refs/remotes/linux-nfs/master: storing branch 'master' ... 405 commit: bf81b46 406------------------------------------------------- 407 408New remote-tracking branches will be stored under the shorthand name 409that you gave "git remote add", in this case linux-nfs: 410 411------------------------------------------------- 412$ git branch -r 413linux-nfs/master 414origin/master 415------------------------------------------------- 416 417If you run "git fetch <remote>" later, the tracking branches for the 418named <remote> will be updated. 419 420If you examine the file .git/config, you will see that git has added 421a new stanza: 422 423------------------------------------------------- 424$ cat .git/config 425... 426[remote "linux-nfs"] 427 url = git://linux-nfs.org/pub/nfs-2.6.git 428 fetch = +refs/heads/*:refs/remotes/linux-nfs/* 429... 430------------------------------------------------- 431 432This is what causes git to track the remote's branches; you may modify 433or delete these configuration options by editing .git/config with a 434text editor. (See the "CONFIGURATION FILE" section of 435gitlink:git-config[1] for details.) 436 437[[exploring-git-history]] 438Exploring git history 439===================== 440 441Git is best thought of as a tool for storing the history of a 442collection of files. It does this by storing compressed snapshots of 443the contents of a file hierarchy, together with "commits" which show 444the relationships between these snapshots. 445 446Git provides extremely flexible and fast tools for exploring the 447history of a project. 448 449We start with one specialized tool that is useful for finding the 450commit that introduced a bug into a project. 451 452[[using-bisect]] 453How to use bisect to find a regression 454-------------------------------------- 455 456Suppose version 2.6.18 of your project worked, but the version at 457"master" crashes. Sometimes the best way to find the cause of such a 458regression is to perform a brute-force search through the project's 459history to find the particular commit that caused the problem. The 460gitlink:git-bisect[1] command can help you do this: 461 462------------------------------------------------- 463$ git bisect start 464$ git bisect good v2.6.18 465$ git bisect bad master 466Bisecting: 3537 revisions left to test after this 467[65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6] 468------------------------------------------------- 469 470If you run "git branch" at this point, you'll see that git has 471temporarily moved you to a new branch named "bisect". This branch 472points to a commit (with commit id 65934...) that is reachable from 473v2.6.19 but not from v2.6.18. Compile and test it, and see whether 474it crashes. Assume it does crash. Then: 475 476------------------------------------------------- 477$ git bisect bad 478Bisecting: 1769 revisions left to test after this 479[7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings 480------------------------------------------------- 481 482checks out an older version. Continue like this, telling git at each 483stage whether the version it gives you is good or bad, and notice 484that the number of revisions left to test is cut approximately in 485half each time. 486 487After about 13 tests (in this case), it will output the commit id of 488the guilty commit. You can then examine the commit with 489gitlink:git-show[1], find out who wrote it, and mail them your bug 490report with the commit id. Finally, run 491 492------------------------------------------------- 493$ git bisect reset 494------------------------------------------------- 495 496to return you to the branch you were on before and delete the 497temporary "bisect" branch. 498 499Note that the version which git-bisect checks out for you at each 500point is just a suggestion, and you're free to try a different 501version if you think it would be a good idea. For example, 502occasionally you may land on a commit that broke something unrelated; 503run 504 505------------------------------------------------- 506$ git bisect visualize 507------------------------------------------------- 508 509which will run gitk and label the commit it chose with a marker that 510says "bisect". Chose a safe-looking commit nearby, note its commit 511id, and check it out with: 512 513------------------------------------------------- 514$ git reset --hard fb47ddb2db... 515------------------------------------------------- 516 517then test, run "bisect good" or "bisect bad" as appropriate, and 518continue. 519 520[[naming-commits]] 521Naming commits 522-------------- 523 524We have seen several ways of naming commits already: 525 526 - 40-hexdigit object name 527 - branch name: refers to the commit at the head of the given 528 branch 529 - tag name: refers to the commit pointed to by the given tag 530 (we've seen branches and tags are special cases of 531 <<how-git-stores-references,references>>). 532 - HEAD: refers to the head of the current branch 533 534There are many more; see the "SPECIFYING REVISIONS" section of the 535gitlink:git-rev-parse[1] man page for the complete list of ways to 536name revisions. Some examples: 537 538------------------------------------------------- 539$ git show fb47ddb2 # the first few characters of the object name 540 # are usually enough to specify it uniquely 541$ git show HEAD^ # the parent of the HEAD commit 542$ git show HEAD^^ # the grandparent 543$ git show HEAD~4 # the great-great-grandparent 544------------------------------------------------- 545 546Recall that merge commits may have more than one parent; by default, 547^ and ~ follow the first parent listed in the commit, but you can 548also choose: 549 550------------------------------------------------- 551$ git show HEAD^1 # show the first parent of HEAD 552$ git show HEAD^2 # show the second parent of HEAD 553------------------------------------------------- 554 555In addition to HEAD, there are several other special names for 556commits: 557 558Merges (to be discussed later), as well as operations such as 559git-reset, which change the currently checked-out commit, generally 560set ORIG_HEAD to the value HEAD had before the current operation. 561 562The git-fetch operation always stores the head of the last fetched 563branch in FETCH_HEAD. For example, if you run git fetch without 564specifying a local branch as the target of the operation 565 566------------------------------------------------- 567$ git fetch git://example.com/proj.git theirbranch 568------------------------------------------------- 569 570the fetched commits will still be available from FETCH_HEAD. 571 572When we discuss merges we'll also see the special name MERGE_HEAD, 573which refers to the other branch that we're merging in to the current 574branch. 575 576The gitlink:git-rev-parse[1] command is a low-level command that is 577occasionally useful for translating some name for a commit to the object 578name for that commit: 579 580------------------------------------------------- 581$ git rev-parse origin 582e05db0fd4f31dde7005f075a84f96b360d05984b 583------------------------------------------------- 584 585[[creating-tags]] 586Creating tags 587------------- 588 589We can also create a tag to refer to a particular commit; after 590running 591 592------------------------------------------------- 593$ git tag stable-1 1b2e1d63ff 594------------------------------------------------- 595 596You can use stable-1 to refer to the commit 1b2e1d63ff. 597 598This creates a "lightweight" tag. If you would also like to include a 599comment with the tag, and possibly sign it cryptographically, then you 600should create a tag object instead; see the gitlink:git-tag[1] man page 601for details. 602 603[[browsing-revisions]] 604Browsing revisions 605------------------ 606 607The gitlink:git-log[1] command can show lists of commits. On its 608own, it shows all commits reachable from the parent commit; but you 609can also make more specific requests: 610 611------------------------------------------------- 612$ git log v2.5.. # commits since (not reachable from) v2.5 613$ git log test..master # commits reachable from master but not test 614$ git log master..test # ...reachable from test but not master 615$ git log master...test # ...reachable from either test or master, 616 # but not both 617$ git log --since="2 weeks ago" # commits from the last 2 weeks 618$ git log Makefile # commits which modify Makefile 619$ git log fs/ # ... which modify any file under fs/ 620$ git log -S'foo()' # commits which add or remove any file data 621 # matching the string 'foo()' 622------------------------------------------------- 623 624And of course you can combine all of these; the following finds 625commits since v2.5 which touch the Makefile or any file under fs: 626 627------------------------------------------------- 628$ git log v2.5.. Makefile fs/ 629------------------------------------------------- 630 631You can also ask git log to show patches: 632 633------------------------------------------------- 634$ git log -p 635------------------------------------------------- 636 637See the "--pretty" option in the gitlink:git-log[1] man page for more 638display options. 639 640Note that git log starts with the most recent commit and works 641backwards through the parents; however, since git history can contain 642multiple independent lines of development, the particular order that 643commits are listed in may be somewhat arbitrary. 644 645[[generating-diffs]] 646Generating diffs 647---------------- 648 649You can generate diffs between any two versions using 650gitlink:git-diff[1]: 651 652------------------------------------------------- 653$ git diff master..test 654------------------------------------------------- 655 656Sometimes what you want instead is a set of patches: 657 658------------------------------------------------- 659$ git format-patch master..test 660------------------------------------------------- 661 662will generate a file with a patch for each commit reachable from test 663but not from master. Note that if master also has commits which are 664not reachable from test, then the combined result of these patches 665will not be the same as the diff produced by the git-diff example. 666 667[[viewing-old-file-versions]] 668Viewing old file versions 669------------------------- 670 671You can always view an old version of a file by just checking out the 672correct revision first. But sometimes it is more convenient to be 673able to view an old version of a single file without checking 674anything out; this command does that: 675 676------------------------------------------------- 677$ git show v2.5:fs/locks.c 678------------------------------------------------- 679 680Before the colon may be anything that names a commit, and after it 681may be any path to a file tracked by git. 682 683[[history-examples]] 684Examples 685-------- 686 687[[counting-commits-on-a-branch]] 688Counting the number of commits on a branch 689~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 690 691Suppose you want to know how many commits you've made on "mybranch" 692since it diverged from "origin": 693 694------------------------------------------------- 695$ git log --pretty=oneline origin..mybranch | wc -l 696------------------------------------------------- 697 698Alternatively, you may often see this sort of thing done with the 699lower-level command gitlink:git-rev-list[1], which just lists the SHA1's 700of all the given commits: 701 702------------------------------------------------- 703$ git rev-list origin..mybranch | wc -l 704------------------------------------------------- 705 706[[checking-for-equal-branches]] 707Check whether two branches point at the same history 708~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 709 710Suppose you want to check whether two branches point at the same point 711in history. 712 713------------------------------------------------- 714$ git diff origin..master 715------------------------------------------------- 716 717will tell you whether the contents of the project are the same at the 718two branches; in theory, however, it's possible that the same project 719contents could have been arrived at by two different historical 720routes. You could compare the object names: 721 722------------------------------------------------- 723$ git rev-list origin 724e05db0fd4f31dde7005f075a84f96b360d05984b 725$ git rev-list master 726e05db0fd4f31dde7005f075a84f96b360d05984b 727------------------------------------------------- 728 729Or you could recall that the ... operator selects all commits 730contained reachable from either one reference or the other but not 731both: so 732 733------------------------------------------------- 734$ git log origin...master 735------------------------------------------------- 736 737will return no commits when the two branches are equal. 738 739[[finding-tagged-descendants]] 740Find first tagged version including a given fix 741~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 742 743Suppose you know that the commit e05db0fd fixed a certain problem. 744You'd like to find the earliest tagged release that contains that 745fix. 746 747Of course, there may be more than one answer--if the history branched 748after commit e05db0fd, then there could be multiple "earliest" tagged 749releases. 750 751You could just visually inspect the commits since e05db0fd: 752 753------------------------------------------------- 754$ gitk e05db0fd.. 755------------------------------------------------- 756 757Or you can use gitlink:git-name-rev[1], which will give the commit a 758name based on any tag it finds pointing to one of the commit's 759descendants: 760 761------------------------------------------------- 762$ git name-rev --tags e05db0fd 763e05db0fd tags/v1.5.0-rc1^0~23 764------------------------------------------------- 765 766The gitlink:git-describe[1] command does the opposite, naming the 767revision using a tag on which the given commit is based: 768 769------------------------------------------------- 770$ git describe e05db0fd 771v1.5.0-rc0-260-ge05db0f 772------------------------------------------------- 773 774but that may sometimes help you guess which tags might come after the 775given commit. 776 777If you just want to verify whether a given tagged version contains a 778given commit, you could use gitlink:git-merge-base[1]: 779 780------------------------------------------------- 781$ git merge-base e05db0fd v1.5.0-rc1 782e05db0fd4f31dde7005f075a84f96b360d05984b 783------------------------------------------------- 784 785The merge-base command finds a common ancestor of the given commits, 786and always returns one or the other in the case where one is a 787descendant of the other; so the above output shows that e05db0fd 788actually is an ancestor of v1.5.0-rc1. 789 790Alternatively, note that 791 792------------------------------------------------- 793$ git log v1.5.0-rc1..e05db0fd 794------------------------------------------------- 795 796will produce empty output if and only if v1.5.0-rc1 includes e05db0fd, 797because it outputs only commits that are not reachable from v1.5.0-rc1. 798 799As yet another alternative, the gitlink:git-show-branch[1] command lists 800the commits reachable from its arguments with a display on the left-hand 801side that indicates which arguments that commit is reachable from. So, 802you can run something like 803 804------------------------------------------------- 805$ git show-branch e05db0fd v1.5.0-rc0 v1.5.0-rc1 v1.5.0-rc2 806! [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if 807available 808 ! [v1.5.0-rc0] GIT v1.5.0 preview 809 ! [v1.5.0-rc1] GIT v1.5.0-rc1 810 ! [v1.5.0-rc2] GIT v1.5.0-rc2 811... 812------------------------------------------------- 813 814then search for a line that looks like 815 816------------------------------------------------- 817+ ++ [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if 818available 819------------------------------------------------- 820 821Which shows that e05db0fd is reachable from itself, from v1.5.0-rc1, and 822from v1.5.0-rc2, but not from v1.5.0-rc0. 823 824[[showing-commits-unique-to-a-branch]] 825Showing commits unique to a given branch 826~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 827 828Suppose you would like to see all the commits reachable from the branch 829head named "master" but not from any other head in your repository. 830 831We can list all the heads in this repository with 832gitlink:git-show-ref[1]: 833 834------------------------------------------------- 835$ git show-ref --heads 836bf62196b5e363d73353a9dcf094c59595f3153b7 refs/heads/core-tutorial 837db768d5504c1bb46f63ee9d6e1772bd047e05bf9 refs/heads/maint 838a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master 83924dbc180ea14dc1aebe09f14c8ecf32010690627 refs/heads/tutorial-2 8401e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes 841------------------------------------------------- 842 843We can get just the branch-head names, and remove "master", with 844the help of the standard utilities cut and grep: 845 846------------------------------------------------- 847$ git show-ref --heads | cut -d' ' -f2 | grep -v '^refs/heads/master' 848refs/heads/core-tutorial 849refs/heads/maint 850refs/heads/tutorial-2 851refs/heads/tutorial-fixes 852------------------------------------------------- 853 854And then we can ask to see all the commits reachable from master 855but not from these other heads: 856 857------------------------------------------------- 858$ gitk master --not $( git show-ref --heads | cut -d' ' -f2 | 859 grep -v '^refs/heads/master' ) 860------------------------------------------------- 861 862Obviously, endless variations are possible; for example, to see all 863commits reachable from some head but not from any tag in the repository: 864 865------------------------------------------------- 866$ gitk $( git show-ref --heads ) --not $( git show-ref --tags ) 867------------------------------------------------- 868 869(See gitlink:git-rev-parse[1] for explanations of commit-selecting 870syntax such as `--not`.) 871 872[[making-a-release]] 873Creating a changelog and tarball for a software release 874~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 875 876The gitlink:git-archive[1] command can create a tar or zip archive from 877any version of a project; for example: 878 879------------------------------------------------- 880$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz 881------------------------------------------------- 882 883will use HEAD to produce a tar archive in which each filename is 884preceded by "project/". 885 886If you're releasing a new version of a software project, you may want 887to simultaneously make a changelog to include in the release 888announcement. 889 890Linus Torvalds, for example, makes new kernel releases by tagging them, 891then running: 892 893------------------------------------------------- 894$ release-script 2.6.12 2.6.13-rc6 2.6.13-rc7 895------------------------------------------------- 896 897where release-script is a shell script that looks like: 898 899------------------------------------------------- 900#!/bin/sh 901stable="$1" 902last="$2" 903new="$3" 904echo "# git tag v$new" 905echo "git archive --prefix=linux-$new/ v$new | gzip -9 > ../linux-$new.tar.gz" 906echo "git diff v$stable v$new | gzip -9 > ../patch-$new.gz" 907echo "git log --no-merges v$new ^v$last > ../ChangeLog-$new" 908echo "git shortlog --no-merges v$new ^v$last > ../ShortLog" 909echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new" 910------------------------------------------------- 911 912and then he just cut-and-pastes the output commands after verifying that 913they look OK. 914 915[[Finding-comments-with-given-content]] 916Finding commits referencing a file with given content 917~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 918 919Somebody hands you a copy of a file, and asks which commits modified a 920file such that it contained the given content either before or after the 921commit. You can find out with this: 922 923------------------------------------------------- 924$ git log --raw --abbrev=40 --pretty=oneline -- filename | 925 grep -B 1 `git hash-object filename` 926------------------------------------------------- 927 928Figuring out why this works is left as an exercise to the (advanced) 929student. The gitlink:git-log[1], gitlink:git-diff-tree[1], and 930gitlink:git-hash-object[1] man pages may prove helpful. 931 932[[Developing-with-git]] 933Developing with git 934=================== 935 936[[telling-git-your-name]] 937Telling git your name 938--------------------- 939 940Before creating any commits, you should introduce yourself to git. The 941easiest way to do so is to make sure the following lines appear in a 942file named .gitconfig in your home directory: 943 944------------------------------------------------ 945[user] 946 name = Your Name Comes Here 947 email = you@yourdomain.example.com 948------------------------------------------------ 949 950(See the "CONFIGURATION FILE" section of gitlink:git-config[1] for 951details on the configuration file.) 952 953 954[[creating-a-new-repository]] 955Creating a new repository 956------------------------- 957 958Creating a new repository from scratch is very easy: 959 960------------------------------------------------- 961$ mkdir project 962$ cd project 963$ git init 964------------------------------------------------- 965 966If you have some initial content (say, a tarball): 967 968------------------------------------------------- 969$ tar -xzvf project.tar.gz 970$ cd project 971$ git init 972$ git add . # include everything below ./ in the first commit: 973$ git commit 974------------------------------------------------- 975 976[[how-to-make-a-commit]] 977How to make a commit 978-------------------- 979 980Creating a new commit takes three steps: 981 982 1. Making some changes to the working directory using your 983 favorite editor. 984 2. Telling git about your changes. 985 3. Creating the commit using the content you told git about 986 in step 2. 987 988In practice, you can interleave and repeat steps 1 and 2 as many 989times as you want: in order to keep track of what you want committed 990at step 3, git maintains a snapshot of the tree's contents in a 991special staging area called "the index." 992 993At the beginning, the content of the index will be identical to 994that of the HEAD. The command "git diff --cached", which shows 995the difference between the HEAD and the index, should therefore 996produce no output at that point. 997 998Modifying the index is easy: 9991000To update the index with the new contents of a modified file, use10011002-------------------------------------------------1003$ git add path/to/file1004-------------------------------------------------10051006To add the contents of a new file to the index, use10071008-------------------------------------------------1009$ git add path/to/file1010-------------------------------------------------10111012To remove a file from the index and from the working tree,10131014-------------------------------------------------1015$ git rm path/to/file1016-------------------------------------------------10171018After each step you can verify that10191020-------------------------------------------------1021$ git diff --cached1022-------------------------------------------------10231024always shows the difference between the HEAD and the index file--this1025is what you'd commit if you created the commit now--and that10261027-------------------------------------------------1028$ git diff1029-------------------------------------------------10301031shows the difference between the working tree and the index file.10321033Note that "git add" always adds just the current contents of a file1034to the index; further changes to the same file will be ignored unless1035you run git-add on the file again.10361037When you're ready, just run10381039-------------------------------------------------1040$ git commit1041-------------------------------------------------10421043and git will prompt you for a commit message and then create the new1044commit. Check to make sure it looks like what you expected with10451046-------------------------------------------------1047$ git show1048-------------------------------------------------10491050As a special shortcut,10511052-------------------------------------------------1053$ git commit -a1054-------------------------------------------------10551056will update the index with any files that you've modified or removed1057and create a commit, all in one step.10581059A number of commands are useful for keeping track of what you're1060about to commit:10611062-------------------------------------------------1063$ git diff --cached # difference between HEAD and the index; what1064 # would be committed if you ran "commit" now.1065$ git diff # difference between the index file and your1066 # working directory; changes that would not1067 # be included if you ran "commit" now.1068$ git diff HEAD # difference between HEAD and working tree; what1069 # would be committed if you ran "commit -a" now.1070$ git status # a brief per-file summary of the above.1071-------------------------------------------------10721073You can also use gitlink:git-gui[1] to create commits, view changes in1074the index and the working tree files, and individually select diff hunks1075for inclusion in the index (by right-clicking on the diff hunk and1076choosing "Stage Hunk For Commit").10771078[[creating-good-commit-messages]]1079Creating good commit messages1080-----------------------------10811082Though not required, it's a good idea to begin the commit message1083with a single short (less than 50 character) line summarizing the1084change, followed by a blank line and then a more thorough1085description. Tools that turn commits into email, for example, use1086the first line on the Subject line and the rest of the commit in the1087body.10881089[[ignoring-files]]1090Ignoring files1091--------------10921093A project will often generate files that you do 'not' want to track with git.1094This typically includes files generated by a build process or temporary1095backup files made by your editor. Of course, 'not' tracking files with git1096is just a matter of 'not' calling "`git add`" on them. But it quickly becomes1097annoying to have these untracked files lying around; e.g. they make1098"`git add .`" and "`git commit -a`" practically useless, and they keep1099showing up in the output of "`git status`".11001101You can tell git to ignore certain files by creating a file called .gitignore1102in the top level of your working directory, with contents such as:11031104-------------------------------------------------1105# Lines starting with '#' are considered comments.1106# Ignore any file named foo.txt.1107foo.txt1108# Ignore (generated) html files,1109*.html1110# except foo.html which is maintained by hand.1111!foo.html1112# Ignore objects and archives.1113*.[oa]1114-------------------------------------------------11151116See gitlink:gitignore[5] for a detailed explanation of the syntax. You can1117also place .gitignore files in other directories in your working tree, and they1118will apply to those directories and their subdirectories. The `.gitignore`1119files can be added to your repository like any other files (just run `git add1120.gitignore` and `git commit`, as usual), which is convenient when the exclude1121patterns (such as patterns matching build output files) would also make sense1122for other users who clone your repository.11231124If you wish the exclude patterns to affect only certain repositories1125(instead of every repository for a given project), you may instead put1126them in a file in your repository named .git/info/exclude, or in any file1127specified by the `core.excludesfile` configuration variable. Some git1128commands can also take exclude patterns directly on the command line.1129See gitlink:gitignore[5] for the details.11301131[[how-to-merge]]1132How to merge1133------------11341135You can rejoin two diverging branches of development using1136gitlink:git-merge[1]:11371138-------------------------------------------------1139$ git merge branchname1140-------------------------------------------------11411142merges the development in the branch "branchname" into the current1143branch. If there are conflicts--for example, if the same file is1144modified in two different ways in the remote branch and the local1145branch--then you are warned; the output may look something like this:11461147-------------------------------------------------1148$ git merge next1149 100% (4/4) done1150Auto-merged file.txt1151CONFLICT (content): Merge conflict in file.txt1152Automatic merge failed; fix conflicts and then commit the result.1153-------------------------------------------------11541155Conflict markers are left in the problematic files, and after1156you resolve the conflicts manually, you can update the index1157with the contents and run git commit, as you normally would when1158creating a new file.11591160If you examine the resulting commit using gitk, you will see that it1161has two parents, one pointing to the top of the current branch, and1162one to the top of the other branch.11631164[[resolving-a-merge]]1165Resolving a merge1166-----------------11671168When a merge isn't resolved automatically, git leaves the index and1169the working tree in a special state that gives you all the1170information you need to help resolve the merge.11711172Files with conflicts are marked specially in the index, so until you1173resolve the problem and update the index, gitlink:git-commit[1] will1174fail:11751176-------------------------------------------------1177$ git commit1178file.txt: needs merge1179-------------------------------------------------11801181Also, gitlink:git-status[1] will list those files as "unmerged", and the1182files with conflicts will have conflict markers added, like this:11831184-------------------------------------------------1185<<<<<<< HEAD:file.txt1186Hello world1187=======1188Goodbye1189>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt1190-------------------------------------------------11911192All you need to do is edit the files to resolve the conflicts, and then11931194-------------------------------------------------1195$ git add file.txt1196$ git commit1197-------------------------------------------------11981199Note that the commit message will already be filled in for you with1200some information about the merge. Normally you can just use this1201default message unchanged, but you may add additional commentary of1202your own if desired.12031204The above is all you need to know to resolve a simple merge. But git1205also provides more information to help resolve conflicts:12061207[[conflict-resolution]]1208Getting conflict-resolution help during a merge1209~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~12101211All of the changes that git was able to merge automatically are1212already added to the index file, so gitlink:git-diff[1] shows only1213the conflicts. It uses an unusual syntax:12141215-------------------------------------------------1216$ git diff1217diff --cc file.txt1218index 802992c,2b60207..00000001219--- a/file.txt1220+++ b/file.txt1221@@@ -1,1 -1,1 +1,5 @@@1222++<<<<<<< HEAD:file.txt1223 +Hello world1224++=======1225+ Goodbye1226++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt1227-------------------------------------------------12281229Recall that the commit which will be committed after we resolve this1230conflict will have two parents instead of the usual one: one parent1231will be HEAD, the tip of the current branch; the other will be the1232tip of the other branch, which is stored temporarily in MERGE_HEAD.12331234During the merge, the index holds three versions of each file. Each of1235these three "file stages" represents a different version of the file:12361237-------------------------------------------------1238$ git show :1:file.txt # the file in a common ancestor of both branches1239$ git show :2:file.txt # the version from HEAD, but including any1240 # nonconflicting changes from MERGE_HEAD1241$ git show :3:file.txt # the version from MERGE_HEAD, but including any1242 # nonconflicting changes from HEAD.1243-------------------------------------------------12441245Since the stage 2 and stage 3 versions have already been updated with1246nonconflicting changes, the only remaining differences between them are1247the important ones; thus gitlink:git-diff[1] can use the information in1248the index to show only those conflicts.12491250The diff above shows the differences between the working-tree version of1251file.txt and the stage 2 and stage 3 versions. So instead of preceding1252each line by a single "+" or "-", it now uses two columns: the first1253column is used for differences between the first parent and the working1254directory copy, and the second for differences between the second parent1255and the working directory copy. (See the "COMBINED DIFF FORMAT" section1256of gitlink:git-diff-files[1] for a details of the format.)12571258After resolving the conflict in the obvious way (but before updating the1259index), the diff will look like:12601261-------------------------------------------------1262$ git diff1263diff --cc file.txt1264index 802992c,2b60207..00000001265--- a/file.txt1266+++ b/file.txt1267@@@ -1,1 -1,1 +1,1 @@@1268- Hello world1269 -Goodbye1270++Goodbye world1271-------------------------------------------------12721273This shows that our resolved version deleted "Hello world" from the1274first parent, deleted "Goodbye" from the second parent, and added1275"Goodbye world", which was previously absent from both.12761277Some special diff options allow diffing the working directory against1278any of these stages:12791280-------------------------------------------------1281$ git diff -1 file.txt # diff against stage 11282$ git diff --base file.txt # same as the above1283$ git diff -2 file.txt # diff against stage 21284$ git diff --ours file.txt # same as the above1285$ git diff -3 file.txt # diff against stage 31286$ git diff --theirs file.txt # same as the above.1287-------------------------------------------------12881289The gitlink:git-log[1] and gitk[1] commands also provide special help1290for merges:12911292-------------------------------------------------1293$ git log --merge1294$ gitk --merge1295-------------------------------------------------12961297These will display all commits which exist only on HEAD or on1298MERGE_HEAD, and which touch an unmerged file.12991300You may also use gitlink:git-mergetool[1], which lets you merge the1301unmerged files using external tools such as emacs or kdiff3.13021303Each time you resolve the conflicts in a file and update the index:13041305-------------------------------------------------1306$ git add file.txt1307-------------------------------------------------13081309the different stages of that file will be "collapsed", after which1310git-diff will (by default) no longer show diffs for that file.13111312[[undoing-a-merge]]1313Undoing a merge1314---------------13151316If you get stuck and decide to just give up and throw the whole mess1317away, you can always return to the pre-merge state with13181319-------------------------------------------------1320$ git reset --hard HEAD1321-------------------------------------------------13221323Or, if you've already committed the merge that you want to throw away,13241325-------------------------------------------------1326$ git reset --hard ORIG_HEAD1327-------------------------------------------------13281329However, this last command can be dangerous in some cases--never1330throw away a commit you have already committed if that commit may1331itself have been merged into another branch, as doing so may confuse1332further merges.13331334[[fast-forwards]]1335Fast-forward merges1336-------------------13371338There is one special case not mentioned above, which is treated1339differently. Normally, a merge results in a merge commit, with two1340parents, one pointing at each of the two lines of development that1341were merged.13421343However, if the current branch is a descendant of the other--so every1344commit present in the one is already contained in the other--then git1345just performs a "fast forward"; the head of the current branch is moved1346forward to point at the head of the merged-in branch, without any new1347commits being created.13481349[[fixing-mistakes]]1350Fixing mistakes1351---------------13521353If you've messed up the working tree, but haven't yet committed your1354mistake, you can return the entire working tree to the last committed1355state with13561357-------------------------------------------------1358$ git reset --hard HEAD1359-------------------------------------------------13601361If you make a commit that you later wish you hadn't, there are two1362fundamentally different ways to fix the problem:13631364 1. You can create a new commit that undoes whatever was done1365 by the previous commit. This is the correct thing if your1366 mistake has already been made public.13671368 2. You can go back and modify the old commit. You should1369 never do this if you have already made the history public;1370 git does not normally expect the "history" of a project to1371 change, and cannot correctly perform repeated merges from1372 a branch that has had its history changed.13731374[[reverting-a-commit]]1375Fixing a mistake with a new commit1376~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~13771378Creating a new commit that reverts an earlier change is very easy;1379just pass the gitlink:git-revert[1] command a reference to the bad1380commit; for example, to revert the most recent commit:13811382-------------------------------------------------1383$ git revert HEAD1384-------------------------------------------------13851386This will create a new commit which undoes the change in HEAD. You1387will be given a chance to edit the commit message for the new commit.13881389You can also revert an earlier change, for example, the next-to-last:13901391-------------------------------------------------1392$ git revert HEAD^1393-------------------------------------------------13941395In this case git will attempt to undo the old change while leaving1396intact any changes made since then. If more recent changes overlap1397with the changes to be reverted, then you will be asked to fix1398conflicts manually, just as in the case of <<resolving-a-merge,1399resolving a merge>>.14001401[[fixing-a-mistake-by-editing-history]]1402Fixing a mistake by editing history1403~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~14041405If the problematic commit is the most recent commit, and you have not1406yet made that commit public, then you may just1407<<undoing-a-merge,destroy it using git-reset>>.14081409Alternatively, you1410can edit the working directory and update the index to fix your1411mistake, just as if you were going to <<how-to-make-a-commit,create a1412new commit>>, then run14131414-------------------------------------------------1415$ git commit --amend1416-------------------------------------------------14171418which will replace the old commit by a new commit incorporating your1419changes, giving you a chance to edit the old commit message first.14201421Again, you should never do this to a commit that may already have1422been merged into another branch; use gitlink:git-revert[1] instead in1423that case.14241425It is also possible to edit commits further back in the history, but1426this is an advanced topic to be left for1427<<cleaning-up-history,another chapter>>.14281429[[checkout-of-path]]1430Checking out an old version of a file1431~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~14321433In the process of undoing a previous bad change, you may find it1434useful to check out an older version of a particular file using1435gitlink:git-checkout[1]. We've used git checkout before to switch1436branches, but it has quite different behavior if it is given a path1437name: the command14381439-------------------------------------------------1440$ git checkout HEAD^ path/to/file1441-------------------------------------------------14421443replaces path/to/file by the contents it had in the commit HEAD^, and1444also updates the index to match. It does not change branches.14451446If you just want to look at an old version of the file, without1447modifying the working directory, you can do that with1448gitlink:git-show[1]:14491450-------------------------------------------------1451$ git show HEAD^:path/to/file1452-------------------------------------------------14531454which will display the given version of the file.14551456[[interrupted-work]]1457Temporarily setting aside work in progress1458~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~14591460While you are in the middle of working on something complicated, you1461find an unrelated but obvious and trivial bug. You would like to fix it1462before continuing. You can use gitlink:git-stash[1] to save the current1463state of your work, and after fixing the bug (or, optionally after doing1464so on a different branch and then coming back), unstash the1465work-in-progress changes.14661467------------------------------------------------1468$ git stash "work in progress for foo feature"1469------------------------------------------------14701471This command will save your changes away to the `stash`, and1472reset your working tree and the index to match the tip of your1473current branch. Then you can make your fix as usual.14741475------------------------------------------------1476... edit and test ...1477$ git commit -a -m "blorpl: typofix"1478------------------------------------------------14791480After that, you can go back to what you were working on with1481`git stash apply`:14821483------------------------------------------------1484$ git stash apply1485------------------------------------------------148614871488[[ensuring-good-performance]]1489Ensuring good performance1490-------------------------14911492On large repositories, git depends on compression to keep the history1493information from taking up to much space on disk or in memory.14941495This compression is not performed automatically. Therefore you1496should occasionally run gitlink:git-gc[1]:14971498-------------------------------------------------1499$ git gc1500-------------------------------------------------15011502to recompress the archive. This can be very time-consuming, so1503you may prefer to run git-gc when you are not doing other work.150415051506[[ensuring-reliability]]1507Ensuring reliability1508--------------------15091510[[checking-for-corruption]]1511Checking the repository for corruption1512~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~15131514The gitlink:git-fsck[1] command runs a number of self-consistency checks1515on the repository, and reports on any problems. This may take some1516time. The most common warning by far is about "dangling" objects:15171518-------------------------------------------------1519$ git fsck1520dangling commit 7281251ddd2a61e38657c827739c57015671a6b31521dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a631522dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b51523dangling blob 218761f9d90712d37a9c5e36f406f92202db07eb1524dangling commit bf093535a34a4d35731aa2bd90fe6b176302f14f1525dangling commit 8e4bec7f2ddaa268bef999853c25755452100f8e1526dangling tree d50bb86186bf27b681d25af89d3b5b68382e40851527dangling tree b24c2473f1fd3d91352a624795be026d64c8841f1528...1529-------------------------------------------------15301531Dangling objects are not a problem. At worst they may take up a little1532extra disk space. They can sometimes provide a last-resort method for1533recovering lost work--see <<dangling-objects>> for details. However, if1534you wish, you can remove them with gitlink:git-prune[1] or the --prune1535option to gitlink:git-gc[1]:15361537-------------------------------------------------1538$ git gc --prune1539-------------------------------------------------15401541This may be time-consuming. Unlike most other git operations (including1542git-gc when run without any options), it is not safe to prune while1543other git operations are in progress in the same repository.15441545[[recovering-lost-changes]]1546Recovering lost changes1547~~~~~~~~~~~~~~~~~~~~~~~15481549[[reflogs]]1550Reflogs1551^^^^^^^15521553Say you modify a branch with gitlink:git-reset[1] --hard, and then1554realize that the branch was the only reference you had to that point in1555history.15561557Fortunately, git also keeps a log, called a "reflog", of all the1558previous values of each branch. So in this case you can still find the1559old history using, for example,15601561-------------------------------------------------1562$ git log master@{1}1563-------------------------------------------------15641565This lists the commits reachable from the previous version of the head.1566This syntax can be used to with any git command that accepts a commit,1567not just with git log. Some other examples:15681569-------------------------------------------------1570$ git show master@{2} # See where the branch pointed 2,1571$ git show master@{3} # 3, ... changes ago.1572$ gitk master@{yesterday} # See where it pointed yesterday,1573$ gitk master@{"1 week ago"} # ... or last week1574$ git log --walk-reflogs master # show reflog entries for master1575-------------------------------------------------15761577A separate reflog is kept for the HEAD, so15781579-------------------------------------------------1580$ git show HEAD@{"1 week ago"}1581-------------------------------------------------15821583will show what HEAD pointed to one week ago, not what the current branch1584pointed to one week ago. This allows you to see the history of what1585you've checked out.15861587The reflogs are kept by default for 30 days, after which they may be1588pruned. See gitlink:git-reflog[1] and gitlink:git-gc[1] to learn1589how to control this pruning, and see the "SPECIFYING REVISIONS"1590section of gitlink:git-rev-parse[1] for details.15911592Note that the reflog history is very different from normal git history.1593While normal history is shared by every repository that works on the1594same project, the reflog history is not shared: it tells you only about1595how the branches in your local repository have changed over time.15961597[[dangling-object-recovery]]1598Examining dangling objects1599^^^^^^^^^^^^^^^^^^^^^^^^^^16001601In some situations the reflog may not be able to save you. For example,1602suppose you delete a branch, then realize you need the history it1603contained. The reflog is also deleted; however, if you have not yet1604pruned the repository, then you may still be able to find the lost1605commits in the dangling objects that git-fsck reports. See1606<<dangling-objects>> for the details.16071608-------------------------------------------------1609$ git fsck1610dangling commit 7281251ddd2a61e38657c827739c57015671a6b31611dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a631612dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b51613...1614-------------------------------------------------16151616You can examine1617one of those dangling commits with, for example,16181619------------------------------------------------1620$ gitk 7281251ddd --not --all1621------------------------------------------------16221623which does what it sounds like: it says that you want to see the commit1624history that is described by the dangling commit(s), but not the1625history that is described by all your existing branches and tags. Thus1626you get exactly the history reachable from that commit that is lost.1627(And notice that it might not be just one commit: we only report the1628"tip of the line" as being dangling, but there might be a whole deep1629and complex commit history that was dropped.)16301631If you decide you want the history back, you can always create a new1632reference pointing to it, for example, a new branch:16331634------------------------------------------------1635$ git branch recovered-branch 7281251ddd1636------------------------------------------------16371638Other types of dangling objects (blobs and trees) are also possible, and1639dangling objects can arise in other situations.164016411642[[sharing-development]]1643Sharing development with others1644===============================16451646[[getting-updates-with-git-pull]]1647Getting updates with git pull1648-----------------------------16491650After you clone a repository and make a few changes of your own, you1651may wish to check the original repository for updates and merge them1652into your own work.16531654We have already seen <<Updating-a-repository-with-git-fetch,how to1655keep remote tracking branches up to date>> with gitlink:git-fetch[1],1656and how to merge two branches. So you can merge in changes from the1657original repository's master branch with:16581659-------------------------------------------------1660$ git fetch1661$ git merge origin/master1662-------------------------------------------------16631664However, the gitlink:git-pull[1] command provides a way to do this in1665one step:16661667-------------------------------------------------1668$ git pull origin master1669-------------------------------------------------16701671In fact, if you have "master" checked out, then by default "git pull"1672merges from the HEAD branch of the origin repository. So often you can1673accomplish the above with just a simple16741675-------------------------------------------------1676$ git pull1677-------------------------------------------------16781679More generally, a branch that is created from a remote branch will pull1680by default from that branch. See the descriptions of the1681branch.<name>.remote and branch.<name>.merge options in1682gitlink:git-config[1], and the discussion of the --track option in1683gitlink:git-checkout[1], to learn how to control these defaults.16841685In addition to saving you keystrokes, "git pull" also helps you by1686producing a default commit message documenting the branch and1687repository that you pulled from.16881689(But note that no such commit will be created in the case of a1690<<fast-forwards,fast forward>>; instead, your branch will just be1691updated to point to the latest commit from the upstream branch.)16921693The git-pull command can also be given "." as the "remote" repository,1694in which case it just merges in a branch from the current repository; so1695the commands16961697-------------------------------------------------1698$ git pull . branch1699$ git merge branch1700-------------------------------------------------17011702are roughly equivalent. The former is actually very commonly used.17031704[[submitting-patches]]1705Submitting patches to a project1706-------------------------------17071708If you just have a few changes, the simplest way to submit them may1709just be to send them as patches in email:17101711First, use gitlink:git-format-patch[1]; for example:17121713-------------------------------------------------1714$ git format-patch origin1715-------------------------------------------------17161717will produce a numbered series of files in the current directory, one1718for each patch in the current branch but not in origin/HEAD.17191720You can then import these into your mail client and send them by1721hand. However, if you have a lot to send at once, you may prefer to1722use the gitlink:git-send-email[1] script to automate the process.1723Consult the mailing list for your project first to determine how they1724prefer such patches be handled.17251726[[importing-patches]]1727Importing patches to a project1728------------------------------17291730Git also provides a tool called gitlink:git-am[1] (am stands for1731"apply mailbox"), for importing such an emailed series of patches.1732Just save all of the patch-containing messages, in order, into a1733single mailbox file, say "patches.mbox", then run17341735-------------------------------------------------1736$ git am -3 patches.mbox1737-------------------------------------------------17381739Git will apply each patch in order; if any conflicts are found, it1740will stop, and you can fix the conflicts as described in1741"<<resolving-a-merge,Resolving a merge>>". (The "-3" option tells1742git to perform a merge; if you would prefer it just to abort and1743leave your tree and index untouched, you may omit that option.)17441745Once the index is updated with the results of the conflict1746resolution, instead of creating a new commit, just run17471748-------------------------------------------------1749$ git am --resolved1750-------------------------------------------------17511752and git will create the commit for you and continue applying the1753remaining patches from the mailbox.17541755The final result will be a series of commits, one for each patch in1756the original mailbox, with authorship and commit log message each1757taken from the message containing each patch.17581759[[public-repositories]]1760Public git repositories1761-----------------------17621763Another way to submit changes to a project is to tell the maintainer1764of that project to pull the changes from your repository using1765gitlink:git-pull[1]. In the section "<<getting-updates-with-git-pull,1766Getting updates with git pull>>" we described this as a way to get1767updates from the "main" repository, but it works just as well in the1768other direction.17691770If you and the maintainer both have accounts on the same machine, then1771you can just pull changes from each other's repositories directly;1772commands that accept repository URLs as arguments will also accept a1773local directory name:17741775-------------------------------------------------1776$ git clone /path/to/repository1777$ git pull /path/to/other/repository1778-------------------------------------------------17791780or an ssh url:17811782-------------------------------------------------1783$ git clone ssh://yourhost/~you/repository1784-------------------------------------------------17851786For projects with few developers, or for synchronizing a few private1787repositories, this may be all you need.17881789However, the more common way to do this is to maintain a separate public1790repository (usually on a different host) for others to pull changes1791from. This is usually more convenient, and allows you to cleanly1792separate private work in progress from publicly visible work.17931794You will continue to do your day-to-day work in your personal1795repository, but periodically "push" changes from your personal1796repository into your public repository, allowing other developers to1797pull from that repository. So the flow of changes, in a situation1798where there is one other developer with a public repository, looks1799like this:18001801 you push1802 your personal repo ------------------> your public repo1803 ^ |1804 | |1805 | you pull | they pull1806 | |1807 | |1808 | they push V1809 their public repo <------------------- their repo18101811We explain how to do this in the following sections.18121813[[setting-up-a-public-repository]]1814Setting up a public repository1815~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~18161817Assume your personal repository is in the directory ~/proj. We1818first create a new clone of the repository and tell git-daemon that it1819is meant to be public:18201821-------------------------------------------------1822$ git clone --bare ~/proj proj.git1823$ touch proj.git/git-daemon-export-ok1824-------------------------------------------------18251826The resulting directory proj.git contains a "bare" git repository--it is1827just the contents of the ".git" directory, without any files checked out1828around it.18291830Next, copy proj.git to the server where you plan to host the1831public repository. You can use scp, rsync, or whatever is most1832convenient.18331834[[exporting-via-git]]1835Exporting a git repository via the git protocol1836~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~18371838This is the preferred method.18391840If someone else administers the server, they should tell you what1841directory to put the repository in, and what git:// url it will appear1842at. You can then skip to the section1843"<<pushing-changes-to-a-public-repository,Pushing changes to a public1844repository>>", below.18451846Otherwise, all you need to do is start gitlink:git-daemon[1]; it will1847listen on port 9418. By default, it will allow access to any directory1848that looks like a git directory and contains the magic file1849git-daemon-export-ok. Passing some directory paths as git-daemon1850arguments will further restrict the exports to those paths.18511852You can also run git-daemon as an inetd service; see the1853gitlink:git-daemon[1] man page for details. (See especially the1854examples section.)18551856[[exporting-via-http]]1857Exporting a git repository via http1858~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~18591860The git protocol gives better performance and reliability, but on a1861host with a web server set up, http exports may be simpler to set up.18621863All you need to do is place the newly created bare git repository in1864a directory that is exported by the web server, and make some1865adjustments to give web clients some extra information they need:18661867-------------------------------------------------1868$ mv proj.git /home/you/public_html/proj.git1869$ cd proj.git1870$ git --bare update-server-info1871$ chmod a+x hooks/post-update1872-------------------------------------------------18731874(For an explanation of the last two lines, see1875gitlink:git-update-server-info[1], and the documentation1876link:hooks.html[Hooks used by git].)18771878Advertise the url of proj.git. Anybody else should then be able to1879clone or pull from that url, for example with a command line like:18801881-------------------------------------------------1882$ git clone http://yourserver.com/~you/proj.git1883-------------------------------------------------18841885(See also1886link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]1887for a slightly more sophisticated setup using WebDAV which also1888allows pushing over http.)18891890[[pushing-changes-to-a-public-repository]]1891Pushing changes to a public repository1892~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~18931894Note that the two techniques outlined above (exporting via1895<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other1896maintainers to fetch your latest changes, but they do not allow write1897access, which you will need to update the public repository with the1898latest changes created in your private repository.18991900The simplest way to do this is using gitlink:git-push[1] and ssh; to1901update the remote branch named "master" with the latest state of your1902branch named "master", run19031904-------------------------------------------------1905$ git push ssh://yourserver.com/~you/proj.git master:master1906-------------------------------------------------19071908or just19091910-------------------------------------------------1911$ git push ssh://yourserver.com/~you/proj.git master1912-------------------------------------------------19131914As with git-fetch, git-push will complain if this does not result in1915a <<fast-forwards,fast forward>>. Normally this is a sign of1916something wrong. However, if you are sure you know what you're1917doing, you may force git-push to perform the update anyway by1918proceeding the branch name by a plus sign:19191920-------------------------------------------------1921$ git push ssh://yourserver.com/~you/proj.git +master1922-------------------------------------------------19231924Note that the target of a "push" is normally a1925<<def_bare_repository,bare>> repository. You can also push to a1926repository that has a checked-out working tree, but the working tree1927will not be updated by the push. This may lead to unexpected results if1928the branch you push to is the currently checked-out branch!19291930As with git-fetch, you may also set up configuration options to1931save typing; so, for example, after19321933-------------------------------------------------1934$ cat >>.git/config <<EOF1935[remote "public-repo"]1936 url = ssh://yourserver.com/~you/proj.git1937EOF1938-------------------------------------------------19391940you should be able to perform the above push with just19411942-------------------------------------------------1943$ git push public-repo master1944-------------------------------------------------19451946See the explanations of the remote.<name>.url, branch.<name>.remote,1947and remote.<name>.push options in gitlink:git-config[1] for1948details.19491950[[setting-up-a-shared-repository]]1951Setting up a shared repository1952~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~19531954Another way to collaborate is by using a model similar to that1955commonly used in CVS, where several developers with special rights1956all push to and pull from a single shared repository. See1957link:cvs-migration.html[git for CVS users] for instructions on how to1958set this up.19591960However, while there is nothing wrong with git's support for shared1961repositories, this mode of operation is not generally recommended,1962simply because the mode of collaboration that git supports--by1963exchanging patches and pulling from public repositories--has so many1964advantages over the central shared repository:19651966 - Git's ability to quickly import and merge patches allows a1967 single maintainer to process incoming changes even at very1968 high rates. And when that becomes too much, git-pull provides1969 an easy way for that maintainer to delegate this job to other1970 maintainers while still allowing optional review of incoming1971 changes.1972 - Since every developer's repository has the same complete copy1973 of the project history, no repository is special, and it is1974 trivial for another developer to take over maintenance of a1975 project, either by mutual agreement, or because a maintainer1976 becomes unresponsive or difficult to work with.1977 - The lack of a central group of "committers" means there is1978 less need for formal decisions about who is "in" and who is1979 "out".19801981[[setting-up-gitweb]]1982Allowing web browsing of a repository1983~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~19841985The gitweb cgi script provides users an easy way to browse your1986project's files and history without having to install git; see the file1987gitweb/INSTALL in the git source tree for instructions on setting it up.19881989[[sharing-development-examples]]1990Examples1991--------19921993[[maintaining-topic-branches]]1994Maintaining topic branches for a Linux subsystem maintainer1995~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~19961997This describes how Tony Luck uses git in his role as maintainer of the1998IA64 architecture for the Linux kernel.19992000He uses two public branches:20012002 - A "test" tree into which patches are initially placed so that they2003 can get some exposure when integrated with other ongoing development.2004 This tree is available to Andrew for pulling into -mm whenever he2005 wants.20062007 - A "release" tree into which tested patches are moved for final sanity2008 checking, and as a vehicle to send them upstream to Linus (by sending2009 him a "please pull" request.)20102011He also uses a set of temporary branches ("topic branches"), each2012containing a logical grouping of patches.20132014To set this up, first create your work tree by cloning Linus's public2015tree:20162017-------------------------------------------------2018$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work2019$ cd work2020-------------------------------------------------20212022Linus's tree will be stored in the remote branch named origin/master,2023and can be updated using gitlink:git-fetch[1]; you can track other2024public trees using gitlink:git-remote[1] to set up a "remote" and2025gitlink:git-fetch[1] to keep them up-to-date; see2026<<repositories-and-branches>>.20272028Now create the branches in which you are going to work; these start out2029at the current tip of origin/master branch, and should be set up (using2030the --track option to gitlink:git-branch[1]) to merge changes in from2031Linus by default.20322033-------------------------------------------------2034$ git branch --track test origin/master2035$ git branch --track release origin/master2036-------------------------------------------------20372038These can be easily kept up to date using gitlink:git-pull[1]20392040-------------------------------------------------2041$ git checkout test && git pull2042$ git checkout release && git pull2043-------------------------------------------------20442045Important note! If you have any local changes in these branches, then2046this merge will create a commit object in the history (with no local2047changes git will simply do a "Fast forward" merge). Many people dislike2048the "noise" that this creates in the Linux history, so you should avoid2049doing this capriciously in the "release" branch, as these noisy commits2050will become part of the permanent history when you ask Linus to pull2051from the release branch.20522053A few configuration variables (see gitlink:git-config[1]) can2054make it easy to push both branches to your public tree. (See2055<<setting-up-a-public-repository>>.)20562057-------------------------------------------------2058$ cat >> .git/config <<EOF2059[remote "mytree"]2060 url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git2061 push = release2062 push = test2063EOF2064-------------------------------------------------20652066Then you can push both the test and release trees using2067gitlink:git-push[1]:20682069-------------------------------------------------2070$ git push mytree2071-------------------------------------------------20722073or push just one of the test and release branches using:20742075-------------------------------------------------2076$ git push mytree test2077-------------------------------------------------20782079or20802081-------------------------------------------------2082$ git push mytree release2083-------------------------------------------------20842085Now to apply some patches from the community. Think of a short2086snappy name for a branch to hold this patch (or related group of2087patches), and create a new branch from the current tip of Linus's2088branch:20892090-------------------------------------------------2091$ git checkout -b speed-up-spinlocks origin2092-------------------------------------------------20932094Now you apply the patch(es), run some tests, and commit the change(s). If2095the patch is a multi-part series, then you should apply each as a separate2096commit to this branch.20972098-------------------------------------------------2099$ ... patch ... test ... commit [ ... patch ... test ... commit ]*2100-------------------------------------------------21012102When you are happy with the state of this change, you can pull it into the2103"test" branch in preparation to make it public:21042105-------------------------------------------------2106$ git checkout test && git pull . speed-up-spinlocks2107-------------------------------------------------21082109It is unlikely that you would have any conflicts here ... but you might if you2110spent a while on this step and had also pulled new versions from upstream.21112112Some time later when enough time has passed and testing done, you can pull the2113same branch into the "release" tree ready to go upstream. This is where you2114see the value of keeping each patch (or patch series) in its own branch. It2115means that the patches can be moved into the "release" tree in any order.21162117-------------------------------------------------2118$ git checkout release && git pull . speed-up-spinlocks2119-------------------------------------------------21202121After a while, you will have a number of branches, and despite the2122well chosen names you picked for each of them, you may forget what2123they are for, or what status they are in. To get a reminder of what2124changes are in a specific branch, use:21252126-------------------------------------------------2127$ git log linux..branchname | git-shortlog2128-------------------------------------------------21292130To see whether it has already been merged into the test or release branches2131use:21322133-------------------------------------------------2134$ git log test..branchname2135-------------------------------------------------21362137or21382139-------------------------------------------------2140$ git log release..branchname2141-------------------------------------------------21422143(If this branch has not yet been merged you will see some log entries.2144If it has been merged, then there will be no output.)21452146Once a patch completes the great cycle (moving from test to release,2147then pulled by Linus, and finally coming back into your local2148"origin/master" branch) the branch for this change is no longer needed.2149You detect this when the output from:21502151-------------------------------------------------2152$ git log origin..branchname2153-------------------------------------------------21542155is empty. At this point the branch can be deleted:21562157-------------------------------------------------2158$ git branch -d branchname2159-------------------------------------------------21602161Some changes are so trivial that it is not necessary to create a separate2162branch and then merge into each of the test and release branches. For2163these changes, just apply directly to the "release" branch, and then2164merge that into the "test" branch.21652166To create diffstat and shortlog summaries of changes to include in a "please2167pull" request to Linus you can use:21682169-------------------------------------------------2170$ git diff --stat origin..release2171-------------------------------------------------21722173and21742175-------------------------------------------------2176$ git log -p origin..release | git shortlog2177-------------------------------------------------21782179Here are some of the scripts that simplify all this even further.21802181-------------------------------------------------2182==== update script ====2183# Update a branch in my GIT tree. If the branch to be updated2184# is origin, then pull from kernel.org. Otherwise merge2185# origin/master branch into test|release branch21862187case "$1" in2188test|release)2189 git checkout $1 && git pull . origin2190 ;;2191origin)2192 before=$(cat .git/refs/remotes/origin/master)2193 git fetch origin2194 after=$(cat .git/refs/remotes/origin/master)2195 if [ $before != $after ]2196 then2197 git log $before..$after | git shortlog2198 fi2199 ;;2200*)2201 echo "Usage: $0 origin|test|release" 1>&22202 exit 12203 ;;2204esac2205-------------------------------------------------22062207-------------------------------------------------2208==== merge script ====2209# Merge a branch into either the test or release branch22102211pname=$022122213usage()2214{2215 echo "Usage: $pname branch test|release" 1>&22216 exit 12217}22182219if [ ! -f .git/refs/heads/"$1" ]2220then2221 echo "Can't see branch <$1>" 1>&22222 usage2223fi22242225case "$2" in2226test|release)2227 if [ $(git log $2..$1 | wc -c) -eq 0 ]2228 then2229 echo $1 already merged into $2 1>&22230 exit 12231 fi2232 git checkout $2 && git pull . $12233 ;;2234*)2235 usage2236 ;;2237esac2238-------------------------------------------------22392240-------------------------------------------------2241==== status script ====2242# report on status of my ia64 GIT tree22432244gb=$(tput setab 2)2245rb=$(tput setab 1)2246restore=$(tput setab 9)22472248if [ `git rev-list test..release | wc -c` -gt 0 ]2249then2250 echo $rb Warning: commits in release that are not in test $restore2251 git log test..release2252fi22532254for branch in `ls .git/refs/heads`2255do2256 if [ $branch = test -o $branch = release ]2257 then2258 continue2259 fi22602261 echo -n $gb ======= $branch ====== $restore " "2262 status=2263 for ref in test release origin/master2264 do2265 if [ `git rev-list $ref..$branch | wc -c` -gt 0 ]2266 then2267 status=$status${ref:0:1}2268 fi2269 done2270 case $status in2271 trl)2272 echo $rb Need to pull into test $restore2273 ;;2274 rl)2275 echo "In test"2276 ;;2277 l)2278 echo "Waiting for linus"2279 ;;2280 "")2281 echo $rb All done $restore2282 ;;2283 *)2284 echo $rb "<$status>" $restore2285 ;;2286 esac2287 git log origin/master..$branch | git shortlog2288done2289-------------------------------------------------229022912292[[cleaning-up-history]]2293Rewriting history and maintaining patch series2294==============================================22952296Normally commits are only added to a project, never taken away or2297replaced. Git is designed with this assumption, and violating it will2298cause git's merge machinery (for example) to do the wrong thing.22992300However, there is a situation in which it can be useful to violate this2301assumption.23022303[[patch-series]]2304Creating the perfect patch series2305---------------------------------23062307Suppose you are a contributor to a large project, and you want to add a2308complicated feature, and to present it to the other developers in a way2309that makes it easy for them to read your changes, verify that they are2310correct, and understand why you made each change.23112312If you present all of your changes as a single patch (or commit), they2313may find that it is too much to digest all at once.23142315If you present them with the entire history of your work, complete with2316mistakes, corrections, and dead ends, they may be overwhelmed.23172318So the ideal is usually to produce a series of patches such that:23192320 1. Each patch can be applied in order.23212322 2. Each patch includes a single logical change, together with a2323 message explaining the change.23242325 3. No patch introduces a regression: after applying any initial2326 part of the series, the resulting project still compiles and2327 works, and has no bugs that it didn't have before.23282329 4. The complete series produces the same end result as your own2330 (probably much messier!) development process did.23312332We will introduce some tools that can help you do this, explain how to2333use them, and then explain some of the problems that can arise because2334you are rewriting history.23352336[[using-git-rebase]]2337Keeping a patch series up to date using git-rebase2338--------------------------------------------------23392340Suppose that you create a branch "mywork" on a remote-tracking branch2341"origin", and create some commits on top of it:23422343-------------------------------------------------2344$ git checkout -b mywork origin2345$ vi file.txt2346$ git commit2347$ vi otherfile.txt2348$ git commit2349...2350-------------------------------------------------23512352You have performed no merges into mywork, so it is just a simple linear2353sequence of patches on top of "origin":23542355................................................2356 o--o--o <-- origin2357 \2358 o--o--o <-- mywork2359................................................23602361Some more interesting work has been done in the upstream project, and2362"origin" has advanced:23632364................................................2365 o--o--O--o--o--o <-- origin2366 \2367 a--b--c <-- mywork2368................................................23692370At this point, you could use "pull" to merge your changes back in;2371the result would create a new merge commit, like this:23722373................................................2374 o--o--O--o--o--o <-- origin2375 \ \2376 a--b--c--m <-- mywork2377................................................23782379However, if you prefer to keep the history in mywork a simple series of2380commits without any merges, you may instead choose to use2381gitlink:git-rebase[1]:23822383-------------------------------------------------2384$ git checkout mywork2385$ git rebase origin2386-------------------------------------------------23872388This will remove each of your commits from mywork, temporarily saving2389them as patches (in a directory named ".dotest"), update mywork to2390point at the latest version of origin, then apply each of the saved2391patches to the new mywork. The result will look like:239223932394................................................2395 o--o--O--o--o--o <-- origin2396 \2397 a'--b'--c' <-- mywork2398................................................23992400In the process, it may discover conflicts. In that case it will stop2401and allow you to fix the conflicts; after fixing conflicts, use "git2402add" to update the index with those contents, and then, instead of2403running git-commit, just run24042405-------------------------------------------------2406$ git rebase --continue2407-------------------------------------------------24082409and git will continue applying the rest of the patches.24102411At any point you may use the --abort option to abort this process and2412return mywork to the state it had before you started the rebase:24132414-------------------------------------------------2415$ git rebase --abort2416-------------------------------------------------24172418[[modifying-one-commit]]2419Modifying a single commit2420-------------------------24212422We saw in <<fixing-a-mistake-by-editing-history>> that you can replace the2423most recent commit using24242425-------------------------------------------------2426$ git commit --amend2427-------------------------------------------------24282429which will replace the old commit by a new commit incorporating your2430changes, giving you a chance to edit the old commit message first.24312432You can also use a combination of this and gitlink:git-rebase[1] to edit2433commits further back in your history. First, tag the problematic commit with24342435-------------------------------------------------2436$ git tag bad mywork~52437-------------------------------------------------24382439(Either gitk or git-log may be useful for finding the commit.)24402441Then check out that commit, edit it, and rebase the rest of the series2442on top of it (note that we could check out the commit on a temporary2443branch, but instead we're using a <<detached-head,detached head>>):24442445-------------------------------------------------2446$ git checkout bad2447$ # make changes here and update the index2448$ git commit --amend2449$ git rebase --onto HEAD bad mywork2450-------------------------------------------------24512452When you're done, you'll be left with mywork checked out, with the top2453patches on mywork reapplied on top of your modified commit. You can2454then clean up with24552456-------------------------------------------------2457$ git tag -d bad2458-------------------------------------------------24592460Note that the immutable nature of git history means that you haven't really2461"modified" existing commits; instead, you have replaced the old commits with2462new commits having new object names.24632464[[reordering-patch-series]]2465Reordering or selecting from a patch series2466-------------------------------------------24672468Given one existing commit, the gitlink:git-cherry-pick[1] command2469allows you to apply the change introduced by that commit and create a2470new commit that records it. So, for example, if "mywork" points to a2471series of patches on top of "origin", you might do something like:24722473-------------------------------------------------2474$ git checkout -b mywork-new origin2475$ gitk origin..mywork &2476-------------------------------------------------24772478And browse through the list of patches in the mywork branch using gitk,2479applying them (possibly in a different order) to mywork-new using2480cherry-pick, and possibly modifying them as you go using commit --amend.2481The gitlink:git-gui[1] command may also help as it allows you to2482individually select diff hunks for inclusion in the index (by2483right-clicking on the diff hunk and choosing "Stage Hunk for Commit").24842485Another technique is to use git-format-patch to create a series of2486patches, then reset the state to before the patches:24872488-------------------------------------------------2489$ git format-patch origin2490$ git reset --hard origin2491-------------------------------------------------24922493Then modify, reorder, or eliminate patches as preferred before applying2494them again with gitlink:git-am[1].24952496[[patch-series-tools]]2497Other tools2498-----------24992500There are numerous other tools, such as StGIT, which exist for the2501purpose of maintaining a patch series. These are outside of the scope of2502this manual.25032504[[problems-with-rewriting-history]]2505Problems with rewriting history2506-------------------------------25072508The primary problem with rewriting the history of a branch has to do2509with merging. Suppose somebody fetches your branch and merges it into2510their branch, with a result something like this:25112512................................................2513 o--o--O--o--o--o <-- origin2514 \ \2515 t--t--t--m <-- their branch:2516................................................25172518Then suppose you modify the last three commits:25192520................................................2521 o--o--o <-- new head of origin2522 /2523 o--o--O--o--o--o <-- old head of origin2524................................................25252526If we examined all this history together in one repository, it will2527look like:25282529................................................2530 o--o--o <-- new head of origin2531 /2532 o--o--O--o--o--o <-- old head of origin2533 \ \2534 t--t--t--m <-- their branch:2535................................................25362537Git has no way of knowing that the new head is an updated version of2538the old head; it treats this situation exactly the same as it would if2539two developers had independently done the work on the old and new heads2540in parallel. At this point, if someone attempts to merge the new head2541in to their branch, git will attempt to merge together the two (old and2542new) lines of development, instead of trying to replace the old by the2543new. The results are likely to be unexpected.25442545You may still choose to publish branches whose history is rewritten,2546and it may be useful for others to be able to fetch those branches in2547order to examine or test them, but they should not attempt to pull such2548branches into their own work.25492550For true distributed development that supports proper merging,2551published branches should never be rewritten.25522553[[advanced-branch-management]]2554Advanced branch management2555==========================25562557[[fetching-individual-branches]]2558Fetching individual branches2559----------------------------25602561Instead of using gitlink:git-remote[1], you can also choose just2562to update one branch at a time, and to store it locally under an2563arbitrary name:25642565-------------------------------------------------2566$ git fetch origin todo:my-todo-work2567-------------------------------------------------25682569The first argument, "origin", just tells git to fetch from the2570repository you originally cloned from. The second argument tells git2571to fetch the branch named "todo" from the remote repository, and to2572store it locally under the name refs/heads/my-todo-work.25732574You can also fetch branches from other repositories; so25752576-------------------------------------------------2577$ git fetch git://example.com/proj.git master:example-master2578-------------------------------------------------25792580will create a new branch named "example-master" and store in it the2581branch named "master" from the repository at the given URL. If you2582already have a branch named example-master, it will attempt to2583<<fast-forwards,fast-forward>> to the commit given by example.com's2584master branch. In more detail:25852586[[fetch-fast-forwards]]2587git fetch and fast-forwards2588---------------------------25892590In the previous example, when updating an existing branch, "git2591fetch" checks to make sure that the most recent commit on the remote2592branch is a descendant of the most recent commit on your copy of the2593branch before updating your copy of the branch to point at the new2594commit. Git calls this process a <<fast-forwards,fast forward>>.25952596A fast forward looks something like this:25972598................................................2599 o--o--o--o <-- old head of the branch2600 \2601 o--o--o <-- new head of the branch2602................................................260326042605In some cases it is possible that the new head will *not* actually be2606a descendant of the old head. For example, the developer may have2607realized she made a serious mistake, and decided to backtrack,2608resulting in a situation like:26092610................................................2611 o--o--o--o--a--b <-- old head of the branch2612 \2613 o--o--o <-- new head of the branch2614................................................26152616In this case, "git fetch" will fail, and print out a warning.26172618In that case, you can still force git to update to the new head, as2619described in the following section. However, note that in the2620situation above this may mean losing the commits labeled "a" and "b",2621unless you've already created a reference of your own pointing to2622them.26232624[[forcing-fetch]]2625Forcing git fetch to do non-fast-forward updates2626------------------------------------------------26272628If git fetch fails because the new head of a branch is not a2629descendant of the old head, you may force the update with:26302631-------------------------------------------------2632$ git fetch git://example.com/proj.git +master:refs/remotes/example/master2633-------------------------------------------------26342635Note the addition of the "+" sign. Alternatively, you can use the "-f"2636flag to force updates of all the fetched branches, as in:26372638-------------------------------------------------2639$ git fetch -f origin2640-------------------------------------------------26412642Be aware that commits that the old version of example/master pointed at2643may be lost, as we saw in the previous section.26442645[[remote-branch-configuration]]2646Configuring remote branches2647---------------------------26482649We saw above that "origin" is just a shortcut to refer to the2650repository that you originally cloned from. This information is2651stored in git configuration variables, which you can see using2652gitlink:git-config[1]:26532654-------------------------------------------------2655$ git config -l2656core.repositoryformatversion=02657core.filemode=true2658core.logallrefupdates=true2659remote.origin.url=git://git.kernel.org/pub/scm/git/git.git2660remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*2661branch.master.remote=origin2662branch.master.merge=refs/heads/master2663-------------------------------------------------26642665If there are other repositories that you also use frequently, you can2666create similar configuration options to save typing; for example,2667after26682669-------------------------------------------------2670$ git config remote.example.url git://example.com/proj.git2671-------------------------------------------------26722673then the following two commands will do the same thing:26742675-------------------------------------------------2676$ git fetch git://example.com/proj.git master:refs/remotes/example/master2677$ git fetch example master:refs/remotes/example/master2678-------------------------------------------------26792680Even better, if you add one more option:26812682-------------------------------------------------2683$ git config remote.example.fetch master:refs/remotes/example/master2684-------------------------------------------------26852686then the following commands will all do the same thing:26872688-------------------------------------------------2689$ git fetch git://example.com/proj.git master:refs/remotes/example/master2690$ git fetch example master:refs/remotes/example/master2691$ git fetch example2692-------------------------------------------------26932694You can also add a "+" to force the update each time:26952696-------------------------------------------------2697$ git config remote.example.fetch +master:ref/remotes/example/master2698-------------------------------------------------26992700Don't do this unless you're sure you won't mind "git fetch" possibly2701throwing away commits on mybranch.27022703Also note that all of the above configuration can be performed by2704directly editing the file .git/config instead of using2705gitlink:git-config[1].27062707See gitlink:git-config[1] for more details on the configuration2708options mentioned above.270927102711[[git-concepts]]2712Git concepts2713============27142715Git is built on a small number of simple but powerful ideas. While it2716is possible to get things done without understanding them, you will find2717git much more intuitive if you do.27182719We start with the most important, the <<def_object_database,object2720database>> and the <<def_index,index>>.27212722[[the-object-database]]2723The Object Database2724-------------------27252726The object database is literally just a content-addressable collection2727of objects. All objects are named by their content, which is2728approximated by the SHA1 hash of the object itself. Objects may refer2729to other objects (by referencing their SHA1 hash), and so you can2730build up a hierarchy of objects.27312732All objects have a statically determined "type" which is2733determined at object creation time, and which identifies the format of2734the object (i.e. how it is used, and how it can refer to other2735objects). There are currently four different object types: "blob",2736"tree", "commit", and "tag".27372738A <<def_blob_object,"blob" object>> cannot refer to any other object,2739and is, as the name implies, a pure storage object containing some2740user data. It is used to actually store the file data, i.e. a blob2741object is associated with some particular version of some file.27422743A <<def_tree_object,"tree" object>> is an object that ties one or more2744"blob" objects into a directory structure. In addition, a tree object2745can refer to other tree objects, thus creating a directory hierarchy.27462747A <<def_commit_object,"commit" object>> ties such directory hierarchies2748together into a <<def_DAG,directed acyclic graph>> of revisions - each2749"commit" is associated with exactly one tree (the directory hierarchy at2750the time of the commit). In addition, a "commit" refers to one or more2751"parent" commit objects that describe the history of how we arrived at2752that directory hierarchy.27532754As a special case, a commit object with no parents is called the "root"2755commit, and is the point of an initial project commit. Each project2756must have at least one root, and while you can tie several different2757root objects together into one project by creating a commit object which2758has two or more separate roots as its ultimate parents, that's probably2759just going to confuse people. So aim for the notion of "one root object2760per project", even if git itself does not enforce that.27612762A <<def_tag_object,"tag" object>> symbolically identifies and can be2763used to sign other objects. It contains the identifier and type of2764another object, a symbolic name (of course!) and, optionally, a2765signature.27662767The object types in some more detail:27682769[[blob-object]]2770Blob Object2771~~~~~~~~~~~27722773A "blob" object is nothing but a binary blob of data, and doesn't2774refer to anything else. There is no signature or any other2775verification of the data, so while the object is consistent (it 'is'2776indexed by its sha1 hash, so the data itself is certainly correct), it2777has absolutely no other attributes. No name associations, no2778permissions. It is purely a blob of data (i.e. normally "file2779contents").27802781In particular, since the blob is entirely defined by its data, if two2782files in a directory tree (or in multiple different versions of the2783repository) have the same contents, they will share the same blob2784object. The object is totally independent of its location in the2785directory tree, and renaming a file does not change the object that2786file is associated with in any way.27872788A blob is typically created when gitlink:git-update-index[1]2789is run, and its data can be accessed by gitlink:git-cat-file[1].27902791[[tree-object]]2792Tree Object2793~~~~~~~~~~~27942795The next hierarchical object type is the "tree" object. A tree object2796is a list of mode/name/blob data, sorted by name. Alternatively, the2797mode data may specify a directory mode, in which case instead of2798naming a blob, that name is associated with another TREE object.27992800Like the "blob" object, a tree object is uniquely determined by the2801set contents, and so two separate but identical trees will always2802share the exact same object. This is true at all levels, i.e. it's2803true for a "leaf" tree (which does not refer to any other trees, only2804blobs) as well as for a whole subdirectory.28052806For that reason a "tree" object is just a pure data abstraction: it2807has no history, no signatures, no verification of validity, except2808that since the contents are again protected by the hash itself, we can2809trust that the tree is immutable and its contents never change.28102811So you can trust the contents of a tree to be valid, the same way you2812can trust the contents of a blob, but you don't know where those2813contents 'came' from.28142815Side note on trees: since a "tree" object is a sorted list of2816"filename+content", you can create a diff between two trees without2817actually having to unpack two trees. Just ignore all common parts,2818and your diff will look right. In other words, you can effectively2819(and efficiently) tell the difference between any two random trees by2820O(n) where "n" is the size of the difference, rather than the size of2821the tree.28222823Side note 2 on trees: since the name of a "blob" depends entirely and2824exclusively on its contents (i.e. there are no names or permissions2825involved), you can see trivial renames or permission changes by2826noticing that the blob stayed the same. However, renames with data2827changes need a smarter "diff" implementation.28282829A tree is created with gitlink:git-write-tree[1] and2830its data can be accessed by gitlink:git-ls-tree[1].2831Two trees can be compared with gitlink:git-diff-tree[1].28322833[[commit-object]]2834Commit Object2835~~~~~~~~~~~~~28362837The "commit" object is an object that introduces the notion of2838history into the picture. In contrast to the other objects, it2839doesn't just describe the physical state of a tree, it describes how2840we got there, and why.28412842A "commit" is defined by the tree-object that it results in, the2843parent commits (zero, one or more) that led up to that point, and a2844comment on what happened. Again, a commit is not trusted per se:2845the contents are well-defined and "safe" due to the cryptographically2846strong signatures at all levels, but there is no reason to believe2847that the tree is "good" or that the merge information makes sense.2848The parents do not have to actually have any relationship with the2849result, for example.28502851Note on commits: unlike some SCM's, commits do not contain2852rename information or file mode change information. All of that is2853implicit in the trees involved (the result tree, and the result trees2854of the parents), and describing that makes no sense in this idiotic2855file manager.28562857A commit is created with gitlink:git-commit-tree[1] and2858its data can be accessed by gitlink:git-cat-file[1].28592860[[trust]]2861Trust2862~~~~~28632864An aside on the notion of "trust". Trust is really outside the scope2865of "git", but it's worth noting a few things. First off, since2866everything is hashed with SHA1, you 'can' trust that an object is2867intact and has not been messed with by external sources. So the name2868of an object uniquely identifies a known state - just not a state that2869you may want to trust.28702871Furthermore, since the SHA1 signature of a commit refers to the2872SHA1 signatures of the tree it is associated with and the signatures2873of the parent, a single named commit specifies uniquely a whole set2874of history, with full contents. You can't later fake any step of the2875way once you have the name of a commit.28762877So to introduce some real trust in the system, the only thing you need2878to do is to digitally sign just 'one' special note, which includes the2879name of a top-level commit. Your digital signature shows others2880that you trust that commit, and the immutability of the history of2881commits tells others that they can trust the whole history.28822883In other words, you can easily validate a whole archive by just2884sending out a single email that tells the people the name (SHA1 hash)2885of the top commit, and digitally sign that email using something2886like GPG/PGP.28872888To assist in this, git also provides the tag object...28892890[[tag-object]]2891Tag Object2892~~~~~~~~~~28932894Git provides the "tag" object to simplify creating, managing and2895exchanging symbolic and signed tokens. The "tag" object at its2896simplest simply symbolically identifies another object by containing2897the sha1, type and symbolic name.28982899However it can optionally contain additional signature information2900(which git doesn't care about as long as there's less than 8k of2901it). This can then be verified externally to git.29022903Note that despite the tag features, "git" itself only handles content2904integrity; the trust framework (and signature provision and2905verification) has to come from outside.29062907A tag is created with gitlink:git-mktag[1],2908its data can be accessed by gitlink:git-cat-file[1],2909and the signature can be verified by2910gitlink:git-verify-tag[1].291129122913[[the-index]]2914The index2915-----------29162917The index is a binary file (generally kept in .git/index) containing a2918sorted list of path names, each with permissions and the SHA1 of a blob2919object; gitlink:git-ls-files[1] can show you the contents of the index:29202921-------------------------------------------------2922$ git ls-files --stage2923100644 63c918c667fa005ff12ad89437f2fdc80926e21c 0 .gitignore2924100644 5529b198e8d14decbe4ad99db3f7fb632de0439d 0 .mailmap2925100644 6ff87c4664981e4397625791c8ea3bbb5f2279a3 0 COPYING2926100644 a37b2152bd26be2c2289e1f57a292534a51a93c7 0 Documentation/.gitignore2927100644 fbefe9a45b00a54b58d94d06eca48b03d40a50e0 0 Documentation/Makefile2928...2929100644 2511aef8d89ab52be5ec6a5e46236b4b6bcd07ea 0 xdiff/xtypes.h2930100644 2ade97b2574a9f77e7ae4002a4e07a6a38e46d07 0 xdiff/xutils.c2931100644 d5de8292e05e7c36c4b68857c1cf9855e3d2f70a 0 xdiff/xutils.h2932-------------------------------------------------29332934Note that in older documentation you may see the index called the2935"current directory cache" or just the "cache". It has three important2936properties:293729381. The index contains all the information necessary to generate a single2939(uniquely determined) tree object.2940+2941For example, running gitlink:git-commit[1] generates this tree object2942from the index, stores it in the object database, and uses it as the2943tree object associated with the new commit.294429452. The index enables fast comparisons between the tree object it defines2946and the working tree.2947+2948It does this by storing some additional data for each entry (such as2949the last modified time). This data is not displayed above, and is not2950stored in the created tree object, but it can be used to determine2951quickly which files in the working directory differ from what was2952stored in the index, and thus save git from having to read all of the2953data from such files to look for changes.295429553. It can efficiently represent information about merge conflicts2956between different tree objects, allowing each pathname to be2957associated with sufficient information about the trees involved that2958you can create a three-way merge between them.2959+2960We saw in <<conflict-resolution>> that during a merge the index can2961store multiple versions of a single file (called "stages"). The third2962column in the gitlink:git-ls-files[1] output above is the stage2963number, and will take on values other than 0 for files with merge2964conflicts.29652966The index is thus a sort of temporary staging area, which is filled with2967a tree which you are in the process of working on.29682969If you blow the index away entirely, you generally haven't lost any2970information as long as you have the name of the tree that it described.29712972[[low-level-operations]]2973Low-level git operations2974========================29752976Many of the higher-level commands were originally implemented as shell2977scripts using a smaller core of low-level git commands. These can still2978be useful when doing unusual things with git, or just as a way to2979understand its inner workings.29802981[[the-workflow]]2982The Workflow2983------------29842985High-level operations such as gitlink:git-commit[1],2986gitlink:git-checkout[1] and git-reset[1] work by moving data between the2987working tree, the index, and the object database. Git provides2988low-level operations which perform each of these steps individually.29892990Generally, all "git" operations work on the index file. Some operations2991work *purely* on the index file (showing the current state of the2992index), but most operations move data between the index file and either2993the database or the working directory. Thus there are four main2994combinations:29952996[[working-directory-to-index]]2997working directory -> index2998~~~~~~~~~~~~~~~~~~~~~~~~~~29993000The gitlink:git-update-index[1] command updates the index with3001information from the working directory. You generally update the3002index information by just specifying the filename you want to update,3003like so:30043005-------------------------------------------------3006$ git update-index filename3007-------------------------------------------------30083009but to avoid common mistakes with filename globbing etc, the command3010will not normally add totally new entries or remove old entries,3011i.e. it will normally just update existing cache entries.30123013To tell git that yes, you really do realize that certain files no3014longer exist, or that new files should be added, you3015should use the `--remove` and `--add` flags respectively.30163017NOTE! A `--remove` flag does 'not' mean that subsequent filenames will3018necessarily be removed: if the files still exist in your directory3019structure, the index will be updated with their new status, not3020removed. The only thing `--remove` means is that update-cache will be3021considering a removed file to be a valid thing, and if the file really3022does not exist any more, it will update the index accordingly.30233024As a special case, you can also do `git-update-index --refresh`, which3025will refresh the "stat" information of each index to match the current3026stat information. It will 'not' update the object status itself, and3027it will only update the fields that are used to quickly test whether3028an object still matches its old backing store object.30293030The previously introduced gitlink:git-add[1] is just a wrapper for3031gitlink:git-update-index[1].30323033[[index-to-object-database]]3034index -> object database3035~~~~~~~~~~~~~~~~~~~~~~~~30363037You write your current index file to a "tree" object with the program30383039-------------------------------------------------3040$ git write-tree3041-------------------------------------------------30423043that doesn't come with any options - it will just write out the3044current index into the set of tree objects that describe that state,3045and it will return the name of the resulting top-level tree. You can3046use that tree to re-generate the index at any time by going in the3047other direction:30483049[[object-database-to-index]]3050object database -> index3051~~~~~~~~~~~~~~~~~~~~~~~~30523053You read a "tree" file from the object database, and use that to3054populate (and overwrite - don't do this if your index contains any3055unsaved state that you might want to restore later!) your current3056index. Normal operation is just30573058-------------------------------------------------3059$ git-read-tree <sha1 of tree>3060-------------------------------------------------30613062and your index file will now be equivalent to the tree that you saved3063earlier. However, that is only your 'index' file: your working3064directory contents have not been modified.30653066[[index-to-working-directory]]3067index -> working directory3068~~~~~~~~~~~~~~~~~~~~~~~~~~30693070You update your working directory from the index by "checking out"3071files. This is not a very common operation, since normally you'd just3072keep your files updated, and rather than write to your working3073directory, you'd tell the index files about the changes in your3074working directory (i.e. `git-update-index`).30753076However, if you decide to jump to a new version, or check out somebody3077else's version, or just restore a previous tree, you'd populate your3078index file with read-tree, and then you need to check out the result3079with30803081-------------------------------------------------3082$ git-checkout-index filename3083-------------------------------------------------30843085or, if you want to check out all of the index, use `-a`.30863087NOTE! git-checkout-index normally refuses to overwrite old files, so3088if you have an old version of the tree already checked out, you will3089need to use the "-f" flag ('before' the "-a" flag or the filename) to3090'force' the checkout.309130923093Finally, there are a few odds and ends which are not purely moving3094from one representation to the other:30953096[[tying-it-all-together]]3097Tying it all together3098~~~~~~~~~~~~~~~~~~~~~30993100To commit a tree you have instantiated with "git-write-tree", you'd3101create a "commit" object that refers to that tree and the history3102behind it - most notably the "parent" commits that preceded it in3103history.31043105Normally a "commit" has one parent: the previous state of the tree3106before a certain change was made. However, sometimes it can have two3107or more parent commits, in which case we call it a "merge", due to the3108fact that such a commit brings together ("merges") two or more3109previous states represented by other commits.31103111In other words, while a "tree" represents a particular directory state3112of a working directory, a "commit" represents that state in "time",3113and explains how we got there.31143115You create a commit object by giving it the tree that describes the3116state at the time of the commit, and a list of parents:31173118-------------------------------------------------3119$ git-commit-tree <tree> -p <parent> [-p <parent2> ..]3120-------------------------------------------------31213122and then giving the reason for the commit on stdin (either through3123redirection from a pipe or file, or by just typing it at the tty).31243125git-commit-tree will return the name of the object that represents3126that commit, and you should save it away for later use. Normally,3127you'd commit a new `HEAD` state, and while git doesn't care where you3128save the note about that state, in practice we tend to just write the3129result to the file pointed at by `.git/HEAD`, so that we can always see3130what the last committed state was.31313132Here is an ASCII art by Jon Loeliger that illustrates how3133various pieces fit together.31343135------------31363137 commit-tree3138 commit obj3139 +----+3140 | |3141 | |3142 V V3143 +-----------+3144 | Object DB |3145 | Backing |3146 | Store |3147 +-----------+3148 ^3149 write-tree | |3150 tree obj | |3151 | | read-tree3152 | | tree obj3153 V3154 +-----------+3155 | Index |3156 | "cache" |3157 +-----------+3158 update-index ^3159 blob obj | |3160 | |3161 checkout-index -u | | checkout-index3162 stat | | blob obj3163 V3164 +-----------+3165 | Working |3166 | Directory |3167 +-----------+31683169------------317031713172[[examining-the-data]]3173Examining the data3174------------------31753176You can examine the data represented in the object database and the3177index with various helper tools. For every object, you can use3178gitlink:git-cat-file[1] to examine details about the3179object:31803181-------------------------------------------------3182$ git-cat-file -t <objectname>3183-------------------------------------------------31843185shows the type of the object, and once you have the type (which is3186usually implicit in where you find the object), you can use31873188-------------------------------------------------3189$ git-cat-file blob|tree|commit|tag <objectname>3190-------------------------------------------------31913192to show its contents. NOTE! Trees have binary content, and as a result3193there is a special helper for showing that content, called3194`git-ls-tree`, which turns the binary content into a more easily3195readable form.31963197It's especially instructive to look at "commit" objects, since those3198tend to be small and fairly self-explanatory. In particular, if you3199follow the convention of having the top commit name in `.git/HEAD`,3200you can do32013202-------------------------------------------------3203$ git-cat-file commit HEAD3204-------------------------------------------------32053206to see what the top commit was.32073208[[merging-multiple-trees]]3209Merging multiple trees3210----------------------32113212Git helps you do a three-way merge, which you can expand to n-way by3213repeating the merge procedure arbitrary times until you finally3214"commit" the state. The normal situation is that you'd only do one3215three-way merge (two parents), and commit it, but if you like to, you3216can do multiple parents in one go.32173218To do a three-way merge, you need the two sets of "commit" objects3219that you want to merge, use those to find the closest common parent (a3220third "commit" object), and then use those commit objects to find the3221state of the directory ("tree" object) at these points.32223223To get the "base" for the merge, you first look up the common parent3224of two commits with32253226-------------------------------------------------3227$ git-merge-base <commit1> <commit2>3228-------------------------------------------------32293230which will return you the commit they are both based on. You should3231now look up the "tree" objects of those commits, which you can easily3232do with (for example)32333234-------------------------------------------------3235$ git-cat-file commit <commitname> | head -13236-------------------------------------------------32373238since the tree object information is always the first line in a commit3239object.32403241Once you know the three trees you are going to merge (the one "original"3242tree, aka the common tree, and the two "result" trees, aka the branches3243you want to merge), you do a "merge" read into the index. This will3244complain if it has to throw away your old index contents, so you should3245make sure that you've committed those - in fact you would normally3246always do a merge against your last commit (which should thus match what3247you have in your current index anyway).32483249To do the merge, do32503251-------------------------------------------------3252$ git-read-tree -m -u <origtree> <yourtree> <targettree>3253-------------------------------------------------32543255which will do all trivial merge operations for you directly in the3256index file, and you can just write the result out with3257`git-write-tree`.325832593260[[merging-multiple-trees-2]]3261Merging multiple trees, continued3262---------------------------------32633264Sadly, many merges aren't trivial. If there are files that have3265been added.moved or removed, or if both branches have modified the3266same file, you will be left with an index tree that contains "merge3267entries" in it. Such an index tree can 'NOT' be written out to a tree3268object, and you will have to resolve any such merge clashes using3269other tools before you can write out the result.32703271You can examine such index state with `git-ls-files --unmerged`3272command. An example:32733274------------------------------------------------3275$ git-read-tree -m $orig HEAD $target3276$ git-ls-files --unmerged3277100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello.c3278100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello.c3279100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello.c3280------------------------------------------------32813282Each line of the `git-ls-files --unmerged` output begins with3283the blob mode bits, blob SHA1, 'stage number', and the3284filename. The 'stage number' is git's way to say which tree it3285came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD`3286tree, and stage3 `$target` tree.32873288Earlier we said that trivial merges are done inside3289`git-read-tree -m`. For example, if the file did not change3290from `$orig` to `HEAD` nor `$target`, or if the file changed3291from `$orig` to `HEAD` and `$orig` to `$target` the same way,3292obviously the final outcome is what is in `HEAD`. What the3293above example shows is that file `hello.c` was changed from3294`$orig` to `HEAD` and `$orig` to `$target` in a different way.3295You could resolve this by running your favorite 3-way merge3296program, e.g. `diff3`, `merge`, or git's own merge-file, on3297the blob objects from these three stages yourself, like this:32983299------------------------------------------------3300$ git-cat-file blob 263414f... >hello.c~13301$ git-cat-file blob 06fa6a2... >hello.c~23302$ git-cat-file blob cc44c73... >hello.c~33303$ git merge-file hello.c~2 hello.c~1 hello.c~33304------------------------------------------------33053306This would leave the merge result in `hello.c~2` file, along3307with conflict markers if there are conflicts. After verifying3308the merge result makes sense, you can tell git what the final3309merge result for this file is by:33103311-------------------------------------------------3312$ mv -f hello.c~2 hello.c3313$ git-update-index hello.c3314-------------------------------------------------33153316When a path is in unmerged state, running `git-update-index` for3317that path tells git to mark the path resolved.33183319The above is the description of a git merge at the lowest level,3320to help you understand what conceptually happens under the hood.3321In practice, nobody, not even git itself, uses three `git-cat-file`3322for this. There is `git-merge-index` program that extracts the3323stages to temporary files and calls a "merge" script on it:33243325-------------------------------------------------3326$ git-merge-index git-merge-one-file hello.c3327-------------------------------------------------33283329and that is what higher level `git merge -s resolve` is implemented with.33303331[[pack-files]]3332How git stores objects efficiently: pack files3333----------------------------------------------33343335We've seen how git stores each object in a file named after the3336object's SHA1 hash.33373338Unfortunately this system becomes inefficient once a project has a3339lot of objects. Try this on an old project:33403341------------------------------------------------3342$ git count-objects33436930 objects, 47620 kilobytes3344------------------------------------------------33453346The first number is the number of objects which are kept in3347individual files. The second is the amount of space taken up by3348those "loose" objects.33493350You can save space and make git faster by moving these loose objects in3351to a "pack file", which stores a group of objects in an efficient3352compressed format; the details of how pack files are formatted can be3353found in link:technical/pack-format.txt[technical/pack-format.txt].33543355To put the loose objects into a pack, just run git repack:33563357------------------------------------------------3358$ git repack3359Generating pack...3360Done counting 6020 objects.3361Deltifying 6020 objects.3362 100% (6020/6020) done3363Writing 6020 objects.3364 100% (6020/6020) done3365Total 6020, written 6020 (delta 4070), reused 0 (delta 0)3366Pack pack-3e54ad29d5b2e05838c75df582c65257b8d08e1c created.3367------------------------------------------------33683369You can then run33703371------------------------------------------------3372$ git prune3373------------------------------------------------33743375to remove any of the "loose" objects that are now contained in the3376pack. This will also remove any unreferenced objects (which may be3377created when, for example, you use "git reset" to remove a commit).3378You can verify that the loose objects are gone by looking at the3379.git/objects directory or by running33803381------------------------------------------------3382$ git count-objects33830 objects, 0 kilobytes3384------------------------------------------------33853386Although the object files are gone, any commands that refer to those3387objects will work exactly as they did before.33883389The gitlink:git-gc[1] command performs packing, pruning, and more for3390you, so is normally the only high-level command you need.33913392[[dangling-objects]]3393Dangling objects3394----------------33953396The gitlink:git-fsck[1] command will sometimes complain about dangling3397objects. They are not a problem.33983399The most common cause of dangling objects is that you've rebased a3400branch, or you have pulled from somebody else who rebased a branch--see3401<<cleaning-up-history>>. In that case, the old head of the original3402branch still exists, as does everything it pointed to. The branch3403pointer itself just doesn't, since you replaced it with another one.34043405There are also other situations that cause dangling objects. For3406example, a "dangling blob" may arise because you did a "git add" of a3407file, but then, before you actually committed it and made it part of the3408bigger picture, you changed something else in that file and committed3409that *updated* thing - the old state that you added originally ends up3410not being pointed to by any commit or tree, so it's now a dangling blob3411object.34123413Similarly, when the "recursive" merge strategy runs, and finds that3414there are criss-cross merges and thus more than one merge base (which is3415fairly unusual, but it does happen), it will generate one temporary3416midway tree (or possibly even more, if you had lots of criss-crossing3417merges and more than two merge bases) as a temporary internal merge3418base, and again, those are real objects, but the end result will not end3419up pointing to them, so they end up "dangling" in your repository.34203421Generally, dangling objects aren't anything to worry about. They can3422even be very useful: if you screw something up, the dangling objects can3423be how you recover your old tree (say, you did a rebase, and realized3424that you really didn't want to - you can look at what dangling objects3425you have, and decide to reset your head to some old dangling state).34263427For commits, you can just use:34283429------------------------------------------------3430$ gitk <dangling-commit-sha-goes-here> --not --all3431------------------------------------------------34323433This asks for all the history reachable from the given commit but not3434from any branch, tag, or other reference. If you decide it's something3435you want, you can always create a new reference to it, e.g.,34363437------------------------------------------------3438$ git branch recovered-branch <dangling-commit-sha-goes-here>3439------------------------------------------------34403441For blobs and trees, you can't do the same, but you can still examine3442them. You can just do34433444------------------------------------------------3445$ git show <dangling-blob/tree-sha-goes-here>3446------------------------------------------------34473448to show what the contents of the blob were (or, for a tree, basically3449what the "ls" for that directory was), and that may give you some idea3450of what the operation was that left that dangling object.34513452Usually, dangling blobs and trees aren't very interesting. They're3453almost always the result of either being a half-way mergebase (the blob3454will often even have the conflict markers from a merge in it, if you3455have had conflicting merges that you fixed up by hand), or simply3456because you interrupted a "git fetch" with ^C or something like that,3457leaving _some_ of the new objects in the object database, but just3458dangling and useless.34593460Anyway, once you are sure that you're not interested in any dangling3461state, you can just prune all unreachable objects:34623463------------------------------------------------3464$ git prune3465------------------------------------------------34663467and they'll be gone. But you should only run "git prune" on a quiescent3468repository - it's kind of like doing a filesystem fsck recovery: you3469don't want to do that while the filesystem is mounted.34703471(The same is true of "git-fsck" itself, btw - but since3472git-fsck never actually *changes* the repository, it just reports3473on what it found, git-fsck itself is never "dangerous" to run.3474Running it while somebody is actually changing the repository can cause3475confusing and scary messages, but it won't actually do anything bad. In3476contrast, running "git prune" while somebody is actively changing the3477repository is a *BAD* idea).34783479[[hacking-git]]3480Hacking git3481===========34823483This chapter covers internal details of the git implementation which3484probably only git developers need to understand.34853486[[object-details]]3487Object storage format3488---------------------34893490All objects have a statically determined "type" which identifies the3491format of the object (i.e. how it is used, and how it can refer to other3492objects). There are currently four different object types: "blob",3493"tree", "commit", and "tag".34943495Regardless of object type, all objects share the following3496characteristics: they are all deflated with zlib, and have a header3497that not only specifies their type, but also provides size information3498about the data in the object. It's worth noting that the SHA1 hash3499that is used to name the object is the hash of the original data3500plus this header, so `sha1sum` 'file' does not match the object name3501for 'file'.3502(Historical note: in the dawn of the age of git the hash3503was the sha1 of the 'compressed' object.)35043505As a result, the general consistency of an object can always be tested3506independently of the contents or the type of the object: all objects can3507be validated by verifying that (a) their hashes match the content of the3508file and (b) the object successfully inflates to a stream of bytes that3509forms a sequence of <ascii type without space> {plus} <space> {plus} <ascii decimal3510size> {plus} <byte\0> {plus} <binary object data>.35113512The structured objects can further have their structure and3513connectivity to other objects verified. This is generally done with3514the `git-fsck` program, which generates a full dependency graph3515of all objects, and verifies their internal consistency (in addition3516to just verifying their superficial consistency through the hash).35173518[[birdview-on-the-source-code]]3519A birds-eye view of Git's source code3520-------------------------------------35213522It is not always easy for new developers to find their way through Git's3523source code. This section gives you a little guidance to show where to3524start.35253526A good place to start is with the contents of the initial commit, with:35273528----------------------------------------------------3529$ git checkout e83c51633530----------------------------------------------------35313532The initial revision lays the foundation for almost everything git has3533today, but is small enough to read in one sitting.35343535Note that terminology has changed since that revision. For example, the3536README in that revision uses the word "changeset" to describe what we3537now call a <<def_commit_object,commit>>.35383539Also, we do not call it "cache" any more, but "index", however, the3540file is still called `cache.h`. Remark: Not much reason to change it now,3541especially since there is no good single name for it anyway, because it is3542basically _the_ header file which is included by _all_ of Git's C sources.35433544If you grasp the ideas in that initial commit, you should check out a3545more recent version and skim `cache.h`, `object.h` and `commit.h`.35463547In the early days, Git (in the tradition of UNIX) was a bunch of programs3548which were extremely simple, and which you used in scripts, piping the3549output of one into another. This turned out to be good for initial3550development, since it was easier to test new things. However, recently3551many of these parts have become builtins, and some of the core has been3552"libified", i.e. put into libgit.a for performance, portability reasons,3553and to avoid code duplication.35543555By now, you know what the index is (and find the corresponding data3556structures in `cache.h`), and that there are just a couple of object types3557(blobs, trees, commits and tags) which inherit their common structure from3558`struct object`, which is their first member (and thus, you can cast e.g.3559`(struct object *)commit` to achieve the _same_ as `&commit->object`, i.e.3560get at the object name and flags).35613562Now is a good point to take a break to let this information sink in.35633564Next step: get familiar with the object naming. Read <<naming-commits>>.3565There are quite a few ways to name an object (and not only revisions!).3566All of these are handled in `sha1_name.c`. Just have a quick look at3567the function `get_sha1()`. A lot of the special handling is done by3568functions like `get_sha1_basic()` or the likes.35693570This is just to get you into the groove for the most libified part of Git:3571the revision walker.35723573Basically, the initial version of `git log` was a shell script:35743575----------------------------------------------------------------3576$ git-rev-list --pretty $(git-rev-parse --default HEAD "$@") | \3577 LESS=-S ${PAGER:-less}3578----------------------------------------------------------------35793580What does this mean?35813582`git-rev-list` is the original version of the revision walker, which3583_always_ printed a list of revisions to stdout. It is still functional,3584and needs to, since most new Git programs start out as scripts using3585`git-rev-list`.35863587`git-rev-parse` is not as important any more; it was only used to filter out3588options that were relevant for the different plumbing commands that were3589called by the script.35903591Most of what `git-rev-list` did is contained in `revision.c` and3592`revision.h`. It wraps the options in a struct named `rev_info`, which3593controls how and what revisions are walked, and more.35943595The original job of `git-rev-parse` is now taken by the function3596`setup_revisions()`, which parses the revisions and the common command line3597options for the revision walker. This information is stored in the struct3598`rev_info` for later consumption. You can do your own command line option3599parsing after calling `setup_revisions()`. After that, you have to call3600`prepare_revision_walk()` for initialization, and then you can get the3601commits one by one with the function `get_revision()`.36023603If you are interested in more details of the revision walking process,3604just have a look at the first implementation of `cmd_log()`; call3605`git-show v1.3.0~155^2~4` and scroll down to that function (note that you3606no longer need to call `setup_pager()` directly).36073608Nowadays, `git log` is a builtin, which means that it is _contained_ in the3609command `git`. The source side of a builtin is36103611- a function called `cmd_<bla>`, typically defined in `builtin-<bla>.c`,3612 and declared in `builtin.h`,36133614- an entry in the `commands[]` array in `git.c`, and36153616- an entry in `BUILTIN_OBJECTS` in the `Makefile`.36173618Sometimes, more than one builtin is contained in one source file. For3619example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin-log.c`,3620since they share quite a bit of code. In that case, the commands which are3621_not_ named like the `.c` file in which they live have to be listed in3622`BUILT_INS` in the `Makefile`.36233624`git log` looks more complicated in C than it does in the original script,3625but that allows for a much greater flexibility and performance.36263627Here again it is a good point to take a pause.36283629Lesson three is: study the code. Really, it is the best way to learn about3630the organization of Git (after you know the basic concepts).36313632So, think about something which you are interested in, say, "how can I3633access a blob just knowing the object name of it?". The first step is to3634find a Git command with which you can do it. In this example, it is either3635`git show` or `git cat-file`.36363637For the sake of clarity, let's stay with `git cat-file`, because it36383639- is plumbing, and36403641- was around even in the initial commit (it literally went only through3642 some 20 revisions as `cat-file.c`, was renamed to `builtin-cat-file.c`3643 when made a builtin, and then saw less than 10 versions).36443645So, look into `builtin-cat-file.c`, search for `cmd_cat_file()` and look what3646it does.36473648------------------------------------------------------------------3649 git_config(git_default_config);3650 if (argc != 3)3651 usage("git-cat-file [-t|-s|-e|-p|<type>] <sha1>");3652 if (get_sha1(argv[2], sha1))3653 die("Not a valid object name %s", argv[2]);3654------------------------------------------------------------------36553656Let's skip over the obvious details; the only really interesting part3657here is the call to `get_sha1()`. It tries to interpret `argv[2]` as an3658object name, and if it refers to an object which is present in the current3659repository, it writes the resulting SHA-1 into the variable `sha1`.36603661Two things are interesting here:36623663- `get_sha1()` returns 0 on _success_. This might surprise some new3664 Git hackers, but there is a long tradition in UNIX to return different3665 negative numbers in case of different errors -- and 0 on success.36663667- the variable `sha1` in the function signature of `get_sha1()` is `unsigned3668 char \*`, but is actually expected to be a pointer to `unsigned3669 char[20]`. This variable will contain the 160-bit SHA-1 of the given3670 commit. Note that whenever a SHA-1 is passed as `unsigned char \*`, it3671 is the binary representation, as opposed to the ASCII representation in3672 hex characters, which is passed as `char *`.36733674You will see both of these things throughout the code.36753676Now, for the meat:36773678-----------------------------------------------------------------------------3679 case 0:3680 buf = read_object_with_reference(sha1, argv[1], &size, NULL);3681-----------------------------------------------------------------------------36823683This is how you read a blob (actually, not only a blob, but any type of3684object). To know how the function `read_object_with_reference()` actually3685works, find the source code for it (something like `git grep3686read_object_with | grep ":[a-z]"` in the git repository), and read3687the source.36883689To find out how the result can be used, just read on in `cmd_cat_file()`:36903691-----------------------------------3692 write_or_die(1, buf, size);3693-----------------------------------36943695Sometimes, you do not know where to look for a feature. In many such cases,3696it helps to search through the output of `git log`, and then `git show` the3697corresponding commit.36983699Example: If you know that there was some test case for `git bundle`, but3700do not remember where it was (yes, you _could_ `git grep bundle t/`, but that3701does not illustrate the point!):37023703------------------------3704$ git log --no-merges t/3705------------------------37063707In the pager (`less`), just search for "bundle", go a few lines back,3708and see that it is in commit 18449ab0... Now just copy this object name,3709and paste it into the command line37103711-------------------3712$ git show 18449ab03713-------------------37143715Voila.37163717Another example: Find out what to do in order to make some script a3718builtin:37193720-------------------------------------------------3721$ git log --no-merges --diff-filter=A builtin-*.c3722-------------------------------------------------37233724You see, Git is actually the best tool to find out about the source of Git3725itself!37263727[[glossary]]3728include::glossary.txt[]37293730[[git-quick-start]]3731Appendix A: Git Quick Reference3732===============================37333734This is a quick summary of the major commands; the previous chapters3735explain how these work in more detail.37363737[[quick-creating-a-new-repository]]3738Creating a new repository3739-------------------------37403741From a tarball:37423743-----------------------------------------------3744$ tar xzf project.tar.gz3745$ cd project3746$ git init3747Initialized empty Git repository in .git/3748$ git add .3749$ git commit3750-----------------------------------------------37513752From a remote repository:37533754-----------------------------------------------3755$ git clone git://example.com/pub/project.git3756$ cd project3757-----------------------------------------------37583759[[managing-branches]]3760Managing branches3761-----------------37623763-----------------------------------------------3764$ git branch # list all local branches in this repo3765$ git checkout test # switch working directory to branch "test"3766$ git branch new # create branch "new" starting at current HEAD3767$ git branch -d new # delete branch "new"3768-----------------------------------------------37693770Instead of basing new branch on current HEAD (the default), use:37713772-----------------------------------------------3773$ git branch new test # branch named "test"3774$ git branch new v2.6.15 # tag named v2.6.153775$ git branch new HEAD^ # commit before the most recent3776$ git branch new HEAD^^ # commit before that3777$ git branch new test~10 # ten commits before tip of branch "test"3778-----------------------------------------------37793780Create and switch to a new branch at the same time:37813782-----------------------------------------------3783$ git checkout -b new v2.6.153784-----------------------------------------------37853786Update and examine branches from the repository you cloned from:37873788-----------------------------------------------3789$ git fetch # update3790$ git branch -r # list3791 origin/master3792 origin/next3793 ...3794$ git checkout -b masterwork origin/master3795-----------------------------------------------37963797Fetch a branch from a different repository, and give it a new3798name in your repository:37993800-----------------------------------------------3801$ git fetch git://example.com/project.git theirbranch:mybranch3802$ git fetch git://example.com/project.git v2.6.15:mybranch3803-----------------------------------------------38043805Keep a list of repositories you work with regularly:38063807-----------------------------------------------3808$ git remote add example git://example.com/project.git3809$ git remote # list remote repositories3810example3811origin3812$ git remote show example # get details3813* remote example3814 URL: git://example.com/project.git3815 Tracked remote branches3816 master next ...3817$ git fetch example # update branches from example3818$ git branch -r # list all remote branches3819-----------------------------------------------382038213822[[exploring-history]]3823Exploring history3824-----------------38253826-----------------------------------------------3827$ gitk # visualize and browse history3828$ git log # list all commits3829$ git log src/ # ...modifying src/3830$ git log v2.6.15..v2.6.16 # ...in v2.6.16, not in v2.6.153831$ git log master..test # ...in branch test, not in branch master3832$ git log test..master # ...in branch master, but not in test3833$ git log test...master # ...in one branch, not in both3834$ git log -S'foo()' # ...where difference contain "foo()"3835$ git log --since="2 weeks ago"3836$ git log -p # show patches as well3837$ git show # most recent commit3838$ git diff v2.6.15..v2.6.16 # diff between two tagged versions3839$ git diff v2.6.15..HEAD # diff with current head3840$ git grep "foo()" # search working directory for "foo()"3841$ git grep v2.6.15 "foo()" # search old tree for "foo()"3842$ git show v2.6.15:a.txt # look at old version of a.txt3843-----------------------------------------------38443845Search for regressions:38463847-----------------------------------------------3848$ git bisect start3849$ git bisect bad # current version is bad3850$ git bisect good v2.6.13-rc2 # last known good revision3851Bisecting: 675 revisions left to test after this3852 # test here, then:3853$ git bisect good # if this revision is good, or3854$ git bisect bad # if this revision is bad.3855 # repeat until done.3856-----------------------------------------------38573858[[making-changes]]3859Making changes3860--------------38613862Make sure git knows who to blame:38633864------------------------------------------------3865$ cat >>~/.gitconfig <<\EOF3866[user]3867 name = Your Name Comes Here3868 email = you@yourdomain.example.com3869EOF3870------------------------------------------------38713872Select file contents to include in the next commit, then make the3873commit:38743875-----------------------------------------------3876$ git add a.txt # updated file3877$ git add b.txt # new file3878$ git rm c.txt # old file3879$ git commit3880-----------------------------------------------38813882Or, prepare and create the commit in one step:38833884-----------------------------------------------3885$ git commit d.txt # use latest content only of d.txt3886$ git commit -a # use latest content of all tracked files3887-----------------------------------------------38883889[[merging]]3890Merging3891-------38923893-----------------------------------------------3894$ git merge test # merge branch "test" into the current branch3895$ git pull git://example.com/project.git master3896 # fetch and merge in remote branch3897$ git pull . test # equivalent to git merge test3898-----------------------------------------------38993900[[sharing-your-changes]]3901Sharing your changes3902--------------------39033904Importing or exporting patches:39053906-----------------------------------------------3907$ git format-patch origin..HEAD # format a patch for each commit3908 # in HEAD but not in origin3909$ git am mbox # import patches from the mailbox "mbox"3910-----------------------------------------------39113912Fetch a branch in a different git repository, then merge into the3913current branch:39143915-----------------------------------------------3916$ git pull git://example.com/project.git theirbranch3917-----------------------------------------------39183919Store the fetched branch into a local branch before merging into the3920current branch:39213922-----------------------------------------------3923$ git pull git://example.com/project.git theirbranch:mybranch3924-----------------------------------------------39253926After creating commits on a local branch, update the remote3927branch with your commits:39283929-----------------------------------------------3930$ git push ssh://example.com/project.git mybranch:theirbranch3931-----------------------------------------------39323933When remote and local branch are both named "test":39343935-----------------------------------------------3936$ git push ssh://example.com/project.git test3937-----------------------------------------------39383939Shortcut version for a frequently used remote repository:39403941-----------------------------------------------3942$ git remote add example ssh://example.com/project.git3943$ git push example test3944-----------------------------------------------39453946[[repository-maintenance]]3947Repository maintenance3948----------------------39493950Check for corruption:39513952-----------------------------------------------3953$ git fsck3954-----------------------------------------------39553956Recompress, remove unused cruft:39573958-----------------------------------------------3959$ git gc3960-----------------------------------------------396139623963[[todo]]3964Appendix B: Notes and todo list for this manual3965===============================================39663967This is a work in progress.39683969The basic requirements:3970 - It must be readable in order, from beginning to end, by3971 someone intelligent with a basic grasp of the UNIX3972 command line, but without any special knowledge of git. If3973 necessary, any other prerequisites should be specifically3974 mentioned as they arise.3975 - Whenever possible, section headings should clearly describe3976 the task they explain how to do, in language that requires3977 no more knowledge than necessary: for example, "importing3978 patches into a project" rather than "the git-am command"39793980Think about how to create a clear chapter dependency graph that will3981allow people to get to important topics without necessarily reading3982everything in between.39833984Scan Documentation/ for other stuff left out; in particular:3985 howto's3986 some of technical/?3987 hooks3988 list of commands in gitlink:git[1]39893990Scan email archives for other stuff left out39913992Scan man pages to see if any assume more background than this manual3993provides.39943995Simplify beginning by suggesting disconnected head instead of3996temporary branch creation?39973998Add more good examples. Entire sections of just cookbook examples3999might be a good idea; maybe make an "advanced examples" section a4000standard end-of-chapter section?40014002Include cross-references to the glossary, where appropriate.40034004Document shallow clones? See draft 1.5.0 release notes for some4005documentation.40064007Add a section on working with other version control systems, including4008CVS, Subversion, and just imports of series of release tarballs.40094010More details on gitweb?40114012Write a chapter on using plumbing and writing scripts.40134014Alternates, clone -reference, etc.40154016git unpack-objects -r for recovery