1Git User's Manual 2_________________ 3 4This manual is designed to be readable by someone with basic unix 5commandline skills, but no previous knowledge of git. 6 7Chapter 1 gives a brief overview of git commands, without any 8explanation; you can skip to chapter 2 on a first reading. 9 10Chapters 2 and 3 explain how to fetch and study a project using 11git--the tools you'd need to build and test a particular version of a 12software project, to search for regressions, and so on. 13 14Chapter 4 explains how to do development with git, and chapter 5 how 15to share that development with others. 16 17Further chapters cover more specialized topics. 18 19Comprehensive reference documentation is available through the man 20pages. For a command such as "git clone", just use 21 22------------------------------------------------ 23$ man git-clone 24------------------------------------------------ 25 26Git Quick Start 27=============== 28 29This is a quick summary of the major commands; the following chapters 30will explain how these work in more detail. 31 32Creating a new repository 33------------------------- 34 35From a tarball: 36 37----------------------------------------------- 38$ tar xzf project.tar.gz 39$ cd project 40$ git init 41Initialized empty Git repository in .git/ 42$ git add . 43$ git commit 44----------------------------------------------- 45 46From a remote repository: 47 48----------------------------------------------- 49$ git clone git://example.com/pub/project.git 50$ cd project 51----------------------------------------------- 52 53Managing branches 54----------------- 55 56----------------------------------------------- 57$ git branch # list all branches in this repo 58$ git checkout test # switch working directory to branch "test" 59$ git branch new # create branch "new" starting at current HEAD 60$ git branch -d new # delete branch "new" 61----------------------------------------------- 62 63Instead of basing new branch on current HEAD (the default), use: 64 65----------------------------------------------- 66$ git branch new test # branch named "test" 67$ git branch new v2.6.15 # tag named v2.6.15 68$ git branch new HEAD^ # commit before the most recent 69$ git branch new HEAD^^ # commit before that 70$ git branch new test~10 # ten commits before tip of branch "test" 71----------------------------------------------- 72 73Create and switch to a new branch at the same time: 74 75----------------------------------------------- 76$ git checkout -b new v2.6.15 77----------------------------------------------- 78 79Update and examine branches from the repository you cloned from: 80 81----------------------------------------------- 82$ git fetch # update 83$ git branch -r # list 84 origin/master 85 origin/next 86 ... 87$ git branch checkout -b masterwork origin/master 88----------------------------------------------- 89 90Fetch a branch from a different repository, and give it a new 91name in your repository: 92 93----------------------------------------------- 94$ git fetch git://example.com/project.git theirbranch:mybranch 95$ git fetch git://example.com/project.git v2.6.15:mybranch 96----------------------------------------------- 97 98Keep a list of repositories you work with regularly: 99 100----------------------------------------------- 101$ git remote add example git://example.com/project.git 102$ git remote # list remote repositories 103example 104origin 105$ git remote show example # get details 106* remote example 107 URL: git://example.com/project.git 108 Tracked remote branches 109 master next ... 110$ git fetch example # update branches from example 111$ git branch -r # list all remote branches 112----------------------------------------------- 113 114 115Exploring history 116----------------- 117 118----------------------------------------------- 119$ gitk # visualize and browse history 120$ git log # list all commits 121$ git log src/ # ...modifying src/ 122$ git log v2.6.15..v2.6.16 # ...in v2.6.16, not in v2.6.15 123$ git log master..test # ...in branch test, not in branch master 124$ git log test..master # ...in branch master, but not in test 125$ git log test...master # ...in one branch, not in both 126$ git log -S'foo()' # ...where difference contain "foo()" 127$ git log --since="2 weeks ago" 128$ git log -p # show patches as well 129$ git show # most recent commit 130$ git diff v2.6.15..v2.6.16 # diff between two tagged versions 131$ git diff v2.6.15..HEAD # diff with current head 132$ git grep "foo()" # search working directory for "foo()" 133$ git grep v2.6.15 "foo()" # search old tree for "foo()" 134$ git show v2.6.15:a.txt # look at old version of a.txt 135----------------------------------------------- 136 137Searching for regressions: 138 139----------------------------------------------- 140$ git bisect start 141$ git bisect bad # current version is bad 142$ git bisect good v2.6.13-rc2 # last known good revision 143Bisecting: 675 revisions left to test after this 144 # test here, then: 145$ git bisect good # if this revision is good, or 146$ git bisect bad # if this revision is bad. 147 # repeat until done. 148----------------------------------------------- 149 150Making changes 151-------------- 152 153Make sure git knows who to blame: 154 155------------------------------------------------ 156$ cat >~/.gitconfig <<\EOF 157[user] 158name = Your Name Comes Here 159email = you@yourdomain.example.com 160EOF 161------------------------------------------------ 162 163Select file contents to include in the next commit, then make the 164commit: 165 166----------------------------------------------- 167$ git add a.txt # updated file 168$ git add b.txt # new file 169$ git rm c.txt # old file 170$ git commit 171----------------------------------------------- 172 173Or, prepare and create the commit in one step: 174 175----------------------------------------------- 176$ git commit d.txt # use latest content of d.txt 177$ git commit -a # use latest content of all tracked files 178----------------------------------------------- 179 180Merging 181------- 182 183----------------------------------------------- 184$ git merge test # merge branch "test" into the current branch 185$ git pull git://example.com/project.git master 186 # fetch and merge in remote branch 187$ git pull . test # equivalent to git merge test 188----------------------------------------------- 189 190Sharing your changes 191-------------------- 192 193Importing or exporting patches: 194 195----------------------------------------------- 196$ git format-patch origin..HEAD # format a patch for each commit 197 # in HEAD but not in origin 198$ git-am mbox # import patches from the mailbox "mbox" 199----------------------------------------------- 200 201Fetch a branch in a different git repository, then merge into the 202current branch: 203 204----------------------------------------------- 205$ git pull git://example.com/project.git theirbranch 206----------------------------------------------- 207 208Store the fetched branch into a local branch before merging into the 209current branch: 210 211----------------------------------------------- 212$ git pull git://example.com/project.git theirbranch:mybranch 213----------------------------------------------- 214 215After creating commits on a local branch, update the remote 216branch with your commits: 217 218----------------------------------------------- 219$ git push ssh://example.com/project.git mybranch:theirbranch 220----------------------------------------------- 221 222When remote and local branch are both named "test": 223 224----------------------------------------------- 225$ git push ssh://example.com/project.git test 226----------------------------------------------- 227 228Shortcut version for a frequently used remote repository: 229 230----------------------------------------------- 231$ git remote add example ssh://example.com/project.git 232$ git push example test 233----------------------------------------------- 234 235Repositories and Branches 236========================= 237 238How to get a git repository 239--------------------------- 240 241It will be useful to have a git repository to experiment with as you 242read this manual. 243 244The best way to get one is by using the gitlink:git-clone[1] command 245to download a copy of an existing repository for a project that you 246are interested in. If you don't already have a project in mind, here 247are some interesting examples: 248 249------------------------------------------------ 250 # git itself (approx. 10MB download): 251$ git clone git://git.kernel.org/pub/scm/git/git.git 252 # the linux kernel (approx. 150MB download): 253$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git 254------------------------------------------------ 255 256The initial clone may be time-consuming for a large project, but you 257will only need to clone once. 258 259The clone command creates a new directory named after the project 260("git" or "linux-2.6" in the examples above). After you cd into this 261directory, you will see that it contains a copy of the project files, 262together with a special top-level directory named ".git", which 263contains all the information about the history of the project. 264 265In most of the following, examples will be taken from one of the two 266repositories above. 267 268How to check out a different version of a project 269------------------------------------------------- 270 271Git is best thought of as a tool for storing the history of a 272collection of files. It stores the history as a compressed 273collection of interrelated snapshots (versions) of the project's 274contents. 275 276A single git repository may contain multiple branches. Each branch 277is a bookmark referencing a particular point in the project history. 278The gitlink:git-branch[1] command shows you the list of branches: 279 280------------------------------------------------ 281$ git branch 282* master 283------------------------------------------------ 284 285A freshly cloned repository contains a single branch, named "master", 286and the working directory contains the version of the project 287referred to by the master branch. 288 289Most projects also use tags. Tags, like branches, are references 290into the project's history, and can be listed using the 291gitlink:git-tag[1] command: 292 293------------------------------------------------ 294$ git tag -l 295v2.6.11 296v2.6.11-tree 297v2.6.12 298v2.6.12-rc2 299v2.6.12-rc3 300v2.6.12-rc4 301v2.6.12-rc5 302v2.6.12-rc6 303v2.6.13 304... 305------------------------------------------------ 306 307Tags are expected to always point at the same version of a project, 308while branches are expected to advance as development progresses. 309 310Create a new branch pointing to one of these versions and check it 311out using gitlink:git-checkout[1]: 312 313------------------------------------------------ 314$ git checkout -b new v2.6.13 315------------------------------------------------ 316 317The working directory then reflects the contents that the project had 318when it was tagged v2.6.13, and gitlink:git-branch[1] shows two 319branches, with an asterisk marking the currently checked-out branch: 320 321------------------------------------------------ 322$ git branch 323 master 324* new 325------------------------------------------------ 326 327If you decide that you'd rather see version 2.6.17, you can modify 328the current branch to point at v2.6.17 instead, with 329 330------------------------------------------------ 331$ git reset --hard v2.6.17 332------------------------------------------------ 333 334Note that if the current branch was your only reference to a 335particular point in history, then resetting that branch may leave you 336with no way to find the history it used to point to; so use this 337command carefully. 338 339Understanding History: Commits 340------------------------------ 341 342Every change in the history of a project is represented by a commit. 343The gitlink:git-show[1] command shows the most recent commit on the 344current branch: 345 346------------------------------------------------ 347$ git show 348commit 2b5f6dcce5bf94b9b119e9ed8d537098ec61c3d2 349Author: Jamal Hadi Salim <hadi@cyberus.ca> 350Date: Sat Dec 2 22:22:25 2006 -0800 351 352 [XFRM]: Fix aevent structuring to be more complete. 353 354 aevents can not uniquely identify an SA. We break the ABI with this 355 patch, but consensus is that since it is not yet utilized by any 356 (known) application then it is fine (better do it now than later). 357 358 Signed-off-by: Jamal Hadi Salim <hadi@cyberus.ca> 359 Signed-off-by: David S. Miller <davem@davemloft.net> 360 361diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt 362index 8be626f..d7aac9d 100644 363--- a/Documentation/networking/xfrm_sync.txt 364+++ b/Documentation/networking/xfrm_sync.txt 365@@ -47,10 +47,13 @@ aevent_id structure looks like: 366 367 struct xfrm_aevent_id { 368 struct xfrm_usersa_id sa_id; 369+ xfrm_address_t saddr; 370 __u32 flags; 371+ __u32 reqid; 372 }; 373... 374------------------------------------------------ 375 376As you can see, a commit shows who made the latest change, what they 377did, and why. 378 379Every commit has a 40-hexdigit id, sometimes called the "SHA1 id", shown 380on the first line of the "git show" output. You can usually refer to 381a commit by a shorter name, such as a tag or a branch name, but this 382longer id can also be useful. In particular, it is a globally unique 383name for this commit: so if you tell somebody else the SHA1 id (for 384example in email), then you are guaranteed they will see the same 385commit in their repository that you do in yours. 386 387Understanding history: commits, parents, and reachability 388~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 389 390Every commit (except the very first commit in a project) also has a 391parent commit which shows what happened before this commit. 392Following the chain of parents will eventually take you back to the 393beginning of the project. 394 395However, the commits do not form a simple list; git allows lines of 396development to diverge and then reconverge, and the point where two 397lines of development reconverge is called a "merge". The commit 398representing a merge can therefore have more than one parent, with 399each parent representing the most recent commit on one of the lines 400of development leading to that point. 401 402The best way to see how this works is using the gitlink:gitk[1] 403command; running gitk now on a git repository and looking for merge 404commits will help understand how the git organizes history. 405 406In the following, we say that commit X is "reachable" from commit Y 407if commit X is an ancestor of commit Y. Equivalently, you could say 408that Y is a descendent of X, or that there is a chain of parents 409leading from commit Y to commit X. 410 411Undestanding history: History diagrams 412~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 413 414We will sometimes represent git history using diagrams like the one 415below. Commits are shown as "o", and the links between them with 416lines drawn with - / and \. Time goes left to right: 417 418 o--o--o <-- Branch A 419 / 420 o--o--o <-- master 421 \ 422 o--o--o <-- Branch B 423 424If we need to talk about a particular commit, the character "o" may 425be replaced with another letter or number. 426 427Understanding history: What is a branch? 428~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 429 430Though we've been using the word "branch" to mean a kind of reference 431to a particular commit, the word branch is also commonly used to 432refer to the line of commits leading up to that point. In the 433example above, git may think of the branch named "A" as just a 434pointer to one particular commit, but we may refer informally to the 435line of three commits leading up to that point as all being part of 436"branch A". 437 438If we need to make it clear that we're just talking about the most 439recent commit on the branch, we may refer to that commit as the 440"head" of the branch. 441 442Manipulating branches 443--------------------- 444 445Creating, deleting, and modifying branches is quick and easy; here's 446a summary of the commands: 447 448git branch:: 449 list all branches 450git branch <branch>:: 451 create a new branch named <branch>, referencing the same 452 point in history as the current branch 453git branch <branch> <start-point>:: 454 create a new branch named <branch>, referencing 455 <start-point>, which may be specified any way you like, 456 including using a branch name or a tag name 457git branch -d <branch>:: 458 delete the branch <branch>; if the branch you are deleting 459 points to a commit which is not reachable from this branch, 460 this command will fail with a warning. 461git branch -D <branch>:: 462 even if the branch points to a commit not reachable 463 from the current branch, you may know that that commit 464 is still reachable from some other branch or tag. In that 465 case it is safe to use this command to force git to delete 466 the branch. 467git checkout <branch>:: 468 make the current branch <branch>, updating the working 469 directory to reflect the version referenced by <branch> 470git checkout -b <new> <start-point>:: 471 create a new branch <new> referencing <start-point>, and 472 check it out. 473 474It is also useful to know that the special symbol "HEAD" can always 475be used to refer to the current branch. 476 477Examining branches from a remote repository 478------------------------------------------- 479 480The "master" branch that was created at the time you cloned is a copy 481of the HEAD in the repository that you cloned from. That repository 482may also have had other branches, though, and your local repository 483keeps branches which track each of those remote branches, which you 484can view using the "-r" option to gitlink:git-branch[1]: 485 486------------------------------------------------ 487$ git branch -r 488 origin/HEAD 489 origin/html 490 origin/maint 491 origin/man 492 origin/master 493 origin/next 494 origin/pu 495 origin/todo 496------------------------------------------------ 497 498You cannot check out these remote-tracking branches, but you can 499examine them on a branch of your own, just as you would a tag: 500 501------------------------------------------------ 502$ git checkout -b my-todo-copy origin/todo 503------------------------------------------------ 504 505Note that the name "origin" is just the name that git uses by default 506to refer to the repository that you cloned from. 507 508[[how-git-stores-references]] 509How git stores references 510------------------------- 511 512Branches, remote-tracking branches, and tags are all references to 513commits. Git stores these references in the ".git" directory. Most 514of them are stored in .git/refs/: 515 516 - branches are stored in .git/refs/heads 517 - tags are stored in .git/refs/tags 518 - remote-tracking branches for "origin" are stored in 519 .git/refs/remotes/origin/ 520 521If you look at one of these files you will see that they usually 522contain just the SHA1 id of a commit: 523 524------------------------------------------------ 525$ ls .git/refs/heads/ 526master 527$ cat .git/refs/heads/master 528c0f982dcf188d55db9d932a39d4ea7becaa55fed 529------------------------------------------------ 530 531You can refer to a reference by its path relative to the .git 532directory. However, we've seen above that git will also accept 533shorter names; for example, "master" is an acceptable shortcut for 534"refs/heads/master", and "origin/master" is a shortcut for 535"refs/remotes/origin/master". 536 537As another useful shortcut, you can also refer to the "HEAD" of 538"origin" (or any other remote), using just the name of the remote. 539 540For the complete list of paths which git checks for references, and 541how it decides which to choose when there are multiple references 542with the same name, see the "SPECIFYING REVISIONS" section of 543gitlink:git-rev-parse[1]. 544 545[[Updating-a-repository-with-git-fetch]] 546Updating a repository with git fetch 547------------------------------------ 548 549Eventually the developer cloned from will do additional work in her 550repository, creating new commits and advancing the branches to point 551at the new commits. 552 553The command "git fetch", with no arguments, will update all of the 554remote-tracking branches to the latest version found in her 555repository. It will not touch any of your own branches--not even the 556"master" branch that was created for you on clone. 557 558Fetching branches from other repositories 559----------------------------------------- 560 561You can also track branches from repositories other than the one you 562cloned from, using gitlink:git-remote[1]: 563 564------------------------------------------------- 565$ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git 566$ git fetch 567* refs/remotes/linux-nfs/master: storing branch 'master' ... 568 commit: bf81b46 569------------------------------------------------- 570 571New remote-tracking branches will be stored under the shorthand name 572that you gave "git remote add", in this case linux-nfs: 573 574------------------------------------------------- 575$ git branch -r 576linux-nfs/master 577origin/master 578------------------------------------------------- 579 580If you run "git fetch <remote>" later, the tracking branches for the 581named <remote> will be updated. 582 583If you examine the file .git/config, you will see that git has added 584a new stanza: 585 586------------------------------------------------- 587$ cat .git/config 588... 589[remote "linux-nfs"] 590 url = git://linux-nfs.org/~bfields/git.git 591 fetch = +refs/heads/*:refs/remotes/linux-nfs-read/* 592... 593------------------------------------------------- 594 595This is what causes git to track the remote's branches; you may 596modify or delete these configuration options by editing .git/config 597with a text editor. 598 599Fetching individual branches 600---------------------------- 601 602TODO: find another home for this, later on: 603 604You can also choose to update just one branch at a time: 605 606------------------------------------------------- 607$ git fetch origin todo:refs/remotes/origin/todo 608------------------------------------------------- 609 610The first argument, "origin", just tells git to fetch from the 611repository you originally cloned from. The second argument tells git 612to fetch the branch named "todo" from the remote repository, and to 613store it locally under the name refs/remotes/origin/todo; as we saw 614above, remote-tracking branches are stored under 615refs/remotes/<name-of-repository>/<name-of-branch>. 616 617You can also fetch branches from other repositories; so 618 619------------------------------------------------- 620$ git fetch git://example.com/proj.git master:refs/remotes/example/master 621------------------------------------------------- 622 623will create a new reference named "refs/remotes/example/master" and 624store in it the branch named "master" from the repository at the 625given URL. If you already have a branch named 626"refs/remotes/example/master", it will attempt to "fast-forward" to 627the commit given by example.com's master branch. So next we explain 628what a fast-forward is: 629 630[[fast-forwards]] 631Understanding git history: fast-forwards 632---------------------------------------- 633 634In the previous example, when updating an existing branch, "git 635fetch" checks to make sure that the most recent commit on the remote 636branch is a descendant of the most recent commit on your copy of the 637branch before updating your copy of the branch to point at the new 638commit. Git calls this process a "fast forward". 639 640A fast forward looks something like this: 641 642 o--o--o--o <-- old head of the branch 643 \ 644 o--o--o <-- new head of the branch 645 646 647In some cases it is possible that the new head will *not* actually be 648a descendant of the old head. For example, the developer may have 649realized she made a serious mistake, and decided to backtrack, 650resulting in a situation like: 651 652 o--o--o--o--a--b <-- old head of the branch 653 \ 654 o--o--o <-- new head of the branch 655 656 657 658In this case, "git fetch" will fail, and print out a warning. 659 660In that case, you can still force git to update to the new head, as 661described in the following section. However, note that in the 662situation above this may mean losing the commits labeled "a" and "b", 663unless you've already created a reference of your own pointing to 664them. 665 666Forcing git fetch to do non-fast-forward updates 667------------------------------------------------ 668 669If git fetch fails because the new head of a branch is not a 670descendant of the old head, you may force the update with: 671 672------------------------------------------------- 673$ git fetch git://example.com/proj.git +master:refs/remotes/example/master 674------------------------------------------------- 675 676Note the addition of the "+" sign. Be aware that commits which the 677old version of example/master pointed at may be lost, as we saw in 678the previous section. 679 680Configuring remote branches 681--------------------------- 682 683We saw above that "origin" is just a shortcut to refer to the 684repository which you originally cloned from. This information is 685stored in git configuration variables, which you can see using 686gitlink:git-repo-config[1]: 687 688------------------------------------------------- 689$ git-repo-config -l 690core.repositoryformatversion=0 691core.filemode=true 692core.logallrefupdates=true 693remote.origin.url=git://git.kernel.org/pub/scm/git/git.git 694remote.origin.fetch=+refs/heads/*:refs/remotes/origin/* 695branch.master.remote=origin 696branch.master.merge=refs/heads/master 697------------------------------------------------- 698 699If there are other repositories that you also use frequently, you can 700create similar configuration options to save typing; for example, 701after 702 703------------------------------------------------- 704$ git repo-config remote.example.url git://example.com/proj.git 705------------------------------------------------- 706 707then the following two commands will do the same thing: 708 709------------------------------------------------- 710$ git fetch git://example.com/proj.git master:refs/remotes/example/master 711$ git fetch example master:refs/remotes/example/master 712------------------------------------------------- 713 714Even better, if you add one more option: 715 716------------------------------------------------- 717$ git repo-config remote.example.fetch master:refs/remotes/example/master 718------------------------------------------------- 719 720then the following commands will all do the same thing: 721 722------------------------------------------------- 723$ git fetch git://example.com/proj.git master:ref/remotes/example/master 724$ git fetch example master:ref/remotes/example/master 725$ git fetch example example/master 726$ git fetch example 727------------------------------------------------- 728 729You can also add a "+" to force the update each time: 730 731------------------------------------------------- 732$ git repo-config remote.example.fetch +master:ref/remotes/example/master 733------------------------------------------------- 734 735Don't do this unless you're sure you won't mind "git fetch" possibly 736throwing away commits on mybranch. 737 738Also note that all of the above configuration can be performed by 739directly editing the file .git/config instead of using 740gitlink:git-repo-config[1]. 741 742See gitlink:git-repo-config[1] for more details on the configuration 743options mentioned above. 744 745Exploring git history 746===================== 747 748Git is best thought of as a tool for storing the history of a 749collection of files. It does this by storing compressed snapshots of 750the contents of a file heirarchy, together with "commits" which show 751the relationships between these snapshots. 752 753Git provides extremely flexible and fast tools for exploring the 754history of a project. 755 756We start with one specialized tool which is useful for finding the 757commit that introduced a bug into a project. 758 759How to use bisect to find a regression 760-------------------------------------- 761 762Suppose version 2.6.18 of your project worked, but the version at 763"master" crashes. Sometimes the best way to find the cause of such a 764regression is to perform a brute-force search through the project's 765history to find the particular commit that caused the problem. The 766gitlink:git-bisect[1] command can help you do this: 767 768------------------------------------------------- 769$ git bisect start 770$ git bisect good v2.6.18 771$ git bisect bad master 772Bisecting: 3537 revisions left to test after this 773[65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6] 774------------------------------------------------- 775 776If you run "git branch" at this point, you'll see that git has 777temporarily moved you to a new branch named "bisect". This branch 778points to a commit (with commit id 65934...) that is reachable from 779v2.6.19 but not from v2.6.18. Compile and test it, and see whether 780it crashes. Assume it does crash. Then: 781 782------------------------------------------------- 783$ git bisect bad 784Bisecting: 1769 revisions left to test after this 785[7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings 786------------------------------------------------- 787 788checks out an older version. Continue like this, telling git at each 789stage whether the version it gives you is good or bad, and notice 790that the number of revisions left to test is cut approximately in 791half each time. 792 793After about 13 tests (in this case), it will output the commit id of 794the guilty commit. You can then examine the commit with 795gitlink:git-show[1], find out who wrote it, and mail them your bug 796report with the commit id. Finally, run 797 798------------------------------------------------- 799$ git bisect reset 800------------------------------------------------- 801 802to return you to the branch you were on before and delete the 803temporary "bisect" branch. 804 805Note that the version which git-bisect checks out for you at each 806point is just a suggestion, and you're free to try a different 807version if you think it would be a good idea. For example, 808occasionally you may land on a commit that broke something unrelated; 809run 810 811------------------------------------------------- 812$ git bisect-visualize 813------------------------------------------------- 814 815which will run gitk and label the commit it chose with a marker that 816says "bisect". Chose a safe-looking commit nearby, note its commit 817id, and check it out with: 818 819------------------------------------------------- 820$ git reset --hard fb47ddb2db... 821------------------------------------------------- 822 823then test, run "bisect good" or "bisect bad" as appropriate, and 824continue. 825 826Naming commits 827-------------- 828 829We have seen several ways of naming commits already: 830 831 - 40-hexdigit SHA1 id 832 - branch name: refers to the commit at the head of the given 833 branch 834 - tag name: refers to the commit pointed to by the given tag 835 (we've seen branches and tags are special cases of 836 <<how-git-stores-references,references>>). 837 - HEAD: refers to the head of the current branch 838 839There are many more; see the "SPECIFYING REVISIONS" section of the 840gitlink:git-rev-parse[1] man page for the complete list of ways to 841name revisions. Some examples: 842 843------------------------------------------------- 844$ git show fb47ddb2 # the first few characters of the SHA1 id 845 # are usually enough to specify it uniquely 846$ git show HEAD^ # the parent of the HEAD commit 847$ git show HEAD^^ # the grandparent 848$ git show HEAD~4 # the great-great-grandparent 849------------------------------------------------- 850 851Recall that merge commits may have more than one parent; by default, 852^ and ~ follow the first parent listed in the commit, but you can 853also choose: 854 855------------------------------------------------- 856$ git show HEAD^1 # show the first parent of HEAD 857$ git show HEAD^2 # show the second parent of HEAD 858------------------------------------------------- 859 860In addition to HEAD, there are several other special names for 861commits: 862 863Merges (to be discussed later), as well as operations such as 864git-reset, which change the currently checked-out commit, generally 865set ORIG_HEAD to the value HEAD had before the current operation. 866 867The git-fetch operation always stores the head of the last fetched 868branch in FETCH_HEAD. For example, if you run git fetch without 869specifying a local branch as the target of the operation 870 871------------------------------------------------- 872$ git fetch git://example.com/proj.git theirbranch 873------------------------------------------------- 874 875the fetched commits will still be available from FETCH_HEAD. 876 877When we discuss merges we'll also see the special name MERGE_HEAD, 878which refers to the other branch that we're merging in to the current 879branch. 880 881The gitlink:git-rev-parse[1] command is a low-level command that is 882occasionally useful for translating some name for a commit to the SHA1 id for 883that commit: 884 885------------------------------------------------- 886$ git rev-parse origin 887e05db0fd4f31dde7005f075a84f96b360d05984b 888------------------------------------------------- 889 890Creating tags 891------------- 892 893We can also create a tag to refer to a particular commit; after 894running 895 896------------------------------------------------- 897$ git-tag stable-1 1b2e1d63ff 898------------------------------------------------- 899 900You can use stable-1 to refer to the commit 1b2e1d63ff. 901 902This creates a "lightweight" tag. If the tag is a tag you wish to 903share with others, and possibly sign cryptographically, then you 904should create a tag object instead; see the gitlink:git-tag[1] man 905page for details. 906 907Browsing revisions 908------------------ 909 910The gitlink:git-log[1] command can show lists of commits. On its 911own, it shows all commits reachable from the parent commit; but you 912can also make more specific requests: 913 914------------------------------------------------- 915$ git log v2.5.. # commits since (not reachable from) v2.5 916$ git log test..master # commits reachable from master but not test 917$ git log master..test # ...reachable from test but not master 918$ git log master...test # ...reachable from either test or master, 919 # but not both 920$ git log --since="2 weeks ago" # commits from the last 2 weeks 921$ git log Makefile # commits which modify Makefile 922$ git log fs/ # ... which modify any file under fs/ 923$ git log -S'foo()' # commits which add or remove any file data 924 # matching the string 'foo()' 925------------------------------------------------- 926 927And of course you can combine all of these; the following finds 928commits since v2.5 which touch the Makefile or any file under fs: 929 930------------------------------------------------- 931$ git log v2.5.. Makefile fs/ 932------------------------------------------------- 933 934You can also ask git log to show patches: 935 936------------------------------------------------- 937$ git log -p 938------------------------------------------------- 939 940See the "--pretty" option in the gitlink:git-log[1] man page for more 941display options. 942 943Note that git log starts with the most recent commit and works 944backwards through the parents; however, since git history can contain 945multiple independant lines of development, the particular order that 946commits are listed in may be somewhat arbitrary. 947 948Generating diffs 949---------------- 950 951You can generate diffs between any two versions using 952gitlink:git-diff[1]: 953 954------------------------------------------------- 955$ git diff master..test 956------------------------------------------------- 957 958Sometimes what you want instead is a set of patches: 959 960------------------------------------------------- 961$ git format-patch master..test 962------------------------------------------------- 963 964will generate a file with a patch for each commit reachable from test 965but not from master. Note that if master also has commits which are 966not reachable from test, then the combined result of these patches 967will not be the same as the diff produced by the git-diff example. 968 969Viewing old file versions 970------------------------- 971 972You can always view an old version of a file by just checking out the 973correct revision first. But sometimes it is more convenient to be 974able to view an old version of a single file without checking 975anything out; this command does that: 976 977------------------------------------------------- 978$ git show v2.5:fs/locks.c 979------------------------------------------------- 980 981Before the colon may be anything that names a commit, and after it 982may be any path to a file tracked by git. 983 984Examples 985-------- 986 987Check whether two branches point at the same history 988~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 989 990Suppose you want to check whether two branches point at the same point 991in history. 992 993------------------------------------------------- 994$ git diff origin..master 995------------------------------------------------- 996 997will tell you whether the contents of the project are the same at the 998two branches; in theory, however, it's possible that the same project 999contents could have been arrived at by two different historical1000routes. You could compare the SHA1 id's:10011002-------------------------------------------------1003$ git rev-list origin1004e05db0fd4f31dde7005f075a84f96b360d05984b1005$ git rev-list master1006e05db0fd4f31dde7005f075a84f96b360d05984b1007-------------------------------------------------10081009Or you could recall that the ... operator selects all commits1010contained reachable from either one reference or the other but not1011both: so10121013-------------------------------------------------1014$ git log origin...master1015-------------------------------------------------10161017will return no commits when the two branches are equal.10181019Check which tagged version a given fix was first included in1020~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~10211022Suppose you know that the commit e05db0fd fixed a certain problem.1023You'd like to find the earliest tagged release that contains that1024fix.10251026Of course, there may be more than one answer--if the history branched1027after commit e05db0fd, then there could be multiple "earliest" tagged1028releases.10291030You could just visually inspect the commits since e05db0fd:10311032-------------------------------------------------1033$ gitk e05db0fd..1034-------------------------------------------------10351036...10371038Developing with git1039===================10401041Telling git your name1042---------------------10431044Before creating any commits, you should introduce yourself to git. The1045easiest way to do so is:10461047------------------------------------------------1048$ cat >~/.gitconfig <<\EOF1049[user]1050 name = Your Name Comes Here1051 email = you@yourdomain.example.com1052EOF1053------------------------------------------------105410551056Creating a new repository1057-------------------------10581059Creating a new repository from scratch is very easy:10601061-------------------------------------------------1062$ mkdir project1063$ cd project1064$ git init1065-------------------------------------------------10661067If you have some initial content (say, a tarball):10681069-------------------------------------------------1070$ tar -xzvf project.tar.gz1071$ cd project1072$ git init1073$ git add . # include everything below ./ in the first commit:1074$ git commit1075-------------------------------------------------10761077[[how-to-make-a-commit]]1078how to make a commit1079--------------------10801081Creating a new commit takes three steps:10821083 1. Making some changes to the working directory using your1084 favorite editor.1085 2. Telling git about your changes.1086 3. Creating the commit using the content you told git about1087 in step 2.10881089In practice, you can interleave and repeat steps 1 and 2 as many1090times as you want: in order to keep track of what you want committed1091at step 3, git maintains a snapshot of the tree's contents in a1092special staging area called "the index."10931094At the beginning, the content of the index will be identical to1095that of the HEAD. The command "git diff --cached", which shows1096the difference between the HEAD and the index, should therefore1097produce no output at that point.10981099Modifying the index is easy:11001101To update the index with the new contents of a modified file, use11021103-------------------------------------------------1104$ git add path/to/file1105-------------------------------------------------11061107To add the contents of a new file to the index, use11081109-------------------------------------------------1110$ git add path/to/file1111-------------------------------------------------11121113To remove a file from the index and from the working tree,11141115-------------------------------------------------1116$ git rm path/to/file1117-------------------------------------------------11181119After each step you can verify that11201121-------------------------------------------------1122$ git diff --cached1123-------------------------------------------------11241125always shows the difference between the HEAD and the index file--this1126is what you'd commit if you created the commit now--and that11271128-------------------------------------------------1129$ git diff1130-------------------------------------------------11311132shows the difference between the working tree and the index file.11331134Note that "git add" always adds just the current contents of a file1135to the index; further changes to the same file will be ignored unless1136you run git-add on the file again.11371138When you're ready, just run11391140-------------------------------------------------1141$ git commit1142-------------------------------------------------11431144and git will prompt you for a commit message and then create the new1145commmit. Check to make sure it looks like what you expected with11461147-------------------------------------------------1148$ git show1149-------------------------------------------------11501151As a special shortcut,11521153-------------------------------------------------1154$ git commit -a1155-------------------------------------------------11561157will update the index with any files that you've modified or removed1158and create a commit, all in one step.11591160A number of commands are useful for keeping track of what you're1161about to commit:11621163-------------------------------------------------1164$ git diff --cached # difference between HEAD and the index; what1165 # would be commited if you ran "commit" now.1166$ git diff # difference between the index file and your1167 # working directory; changes that would not1168 # be included if you ran "commit" now.1169$ git status # a brief per-file summary of the above.1170-------------------------------------------------11711172creating good commit messages1173-----------------------------11741175Though not required, it's a good idea to begin the commit message1176with a single short (less than 50 character) line summarizing the1177change, followed by a blank line and then a more thorough1178description. Tools that turn commits into email, for example, use1179the first line on the Subject line and the rest of the commit in the1180body.11811182how to merge1183------------11841185You can rejoin two diverging branches of development using1186gitlink:git-merge[1]:11871188-------------------------------------------------1189$ git merge branchname1190-------------------------------------------------11911192merges the development in the branch "branchname" into the current1193branch. If there are conflicts--for example, if the same file is1194modified in two different ways in the remote branch and the local1195branch--then you are warned; the output may look something like this:11961197-------------------------------------------------1198$ git pull . next1199Trying really trivial in-index merge...1200fatal: Merge requires file-level merging1201Nope.1202Merging HEAD with 77976da35a11db4580b80ae27e8d65caf52080861203Merging:120415e2162 world120577976da goodbye1206found 1 common ancestor(s):1207d122ed4 initial1208Auto-merging file.txt1209CONFLICT (content): Merge conflict in file.txt1210Automatic merge failed; fix conflicts and then commit the result.1211-------------------------------------------------12121213Conflict markers are left in the problematic files, and after1214you resolve the conflicts manually, you can update the index1215with the contents and run git commit, as you normally would when1216creating a new file.12171218If you examine the resulting commit using gitk, you will see that it1219has two parents, one pointing to the top of the current branch, and1220one to the top of the other branch.12211222In more detail:12231224[[resolving-a-merge]]1225Resolving a merge1226-----------------12271228When a merge isn't resolved automatically, git leaves the index and1229the working tree in a special state that gives you all the1230information you need to help resolve the merge.12311232Files with conflicts are marked specially in the index, so until you1233resolve the problem and update the index, git commit will fail:12341235-------------------------------------------------1236$ git commit1237file.txt: needs merge1238-------------------------------------------------12391240Also, git status will list those files as "unmerged".12411242All of the changes that git was able to merge automatically are1243already added to the index file, so gitlink:git-diff[1] shows only1244the conflicts. Also, it uses a somewhat unusual syntax:12451246-------------------------------------------------1247$ git diff1248diff --cc file.txt1249index 802992c,2b60207..00000001250--- a/file.txt1251+++ b/file.txt1252@@@ -1,1 -1,1 +1,5 @@@1253++<<<<<<< HEAD:file.txt1254 +Hello world1255++=======1256+ Goodbye1257++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt1258-------------------------------------------------12591260Recall that the commit which will be commited after we resolve this1261conflict will have two parents instead of the usual one: one parent1262will be HEAD, the tip of the current branch; the other will be the1263tip of the other branch, which is stored temporarily in MERGE_HEAD.12641265The diff above shows the differences between the working-tree version1266of file.txt and two previous version: one version from HEAD, and one1267from MERGE_HEAD. So instead of preceding each line by a single "+"1268or "-", it now uses two columns: the first column is used for1269differences between the first parent and the working directory copy,1270and the second for differences between the second parent and the1271working directory copy. Thus after resolving the conflict in the1272obvious way, the diff will look like:12731274-------------------------------------------------1275$ git diff1276diff --cc file.txt1277index 802992c,2b60207..00000001278--- a/file.txt1279+++ b/file.txt1280@@@ -1,1 -1,1 +1,1 @@@1281- Hello world1282 -Goodbye1283++Goodbye world1284-------------------------------------------------12851286This shows that our resolved version deleted "Hello world" from the1287first parent, deleted "Goodbye" from the second parent, and added1288"Goodbye world", which was previously absent from both.12891290The gitlink:git-log[1] command also provides special help for merges:12911292-------------------------------------------------1293$ git log --merge1294-------------------------------------------------12951296This will list all commits which exist only on HEAD or on MERGE_HEAD,1297and which touch an unmerged file.12981299We can now add the resolved version to the index and commit:13001301-------------------------------------------------1302$ git add file.txt1303$ git commit1304-------------------------------------------------13051306Note that the commit message will already be filled in for you with1307some information about the merge. Normally you can just use this1308default message unchanged, but you may add additional commentary of1309your own if desired.13101311[[undoing-a-merge]]1312undoing a merge1313---------------13141315If you get stuck and decide to just give up and throw the whole mess1316away, you can always return to the pre-merge state with13171318-------------------------------------------------1319$ git reset --hard HEAD1320-------------------------------------------------13211322Or, if you've already commited the merge that you want to throw away,13231324-------------------------------------------------1325$ git reset --hard HEAD^1326-------------------------------------------------13271328However, this last command can be dangerous in some cases--never1329throw away a commit you have already committed if that commit may1330itself have been merged into another branch, as doing so may confuse1331further merges.13321333Fast-forward merges1334-------------------13351336There is one special case not mentioned above, which is treated1337differently. Normally, a merge results in a merge commit, with two1338parents, one pointing at each of the two lines of development that1339were merged.13401341However, if one of the two lines of development is completely1342contained within the other--so every commit present in the one is1343already contained in the other--then git just performs a1344<<fast-forwards,fast forward>>; the head of the current branch is1345moved forward to point at the head of the merged-in branch, without1346any new commits being created.13471348Fixing mistakes1349---------------13501351If you've messed up the working tree, but haven't yet committed your1352mistake, you can return the entire working tree to the last committed1353state with13541355-------------------------------------------------1356$ git reset --hard HEAD1357-------------------------------------------------13581359If you make a commit that you later wish you hadn't, there are two1360fundamentally different ways to fix the problem:13611362 1. You can create a new commit that undoes whatever was done1363 by the previous commit. This is the correct thing if your1364 mistake has already been made public.13651366 2. You can go back and modify the old commit. You should1367 never do this if you have already made the history public;1368 git does not normally expect the "history" of a project to1369 change, and cannot correctly perform repeated merges from1370 a branch that has had its history changed.13711372Fixing a mistake with a new commit1373~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~13741375Creating a new commit that reverts an earlier change is very easy;1376just pass the gitlink:git-revert[1] command a reference to the bad1377commit; for example, to revert the most recent commit:13781379-------------------------------------------------1380$ git revert HEAD1381-------------------------------------------------13821383This will create a new commit which undoes the change in HEAD. You1384will be given a chance to edit the commit message for the new commit.13851386You can also revert an earlier change, for example, the next-to-last:13871388-------------------------------------------------1389$ git revert HEAD^1390-------------------------------------------------13911392In this case git will attempt to undo the old change while leaving1393intact any changes made since then. If more recent changes overlap1394with the changes to be reverted, then you will be asked to fix1395conflicts manually, just as in the case of <<resolving-a-merge,1396resolving a merge>>.13971398Fixing a mistake by editing history1399~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~14001401If the problematic commit is the most recent commit, and you have not1402yet made that commit public, then you may just1403<<undoing-a-merge,destroy it using git-reset>>.14041405Alternatively, you1406can edit the working directory and update the index to fix your1407mistake, just as if you were going to <<how-to-make-a-commit,create a1408new commit>>, then run14091410-------------------------------------------------1411$ git commit --amend1412-------------------------------------------------14131414which will replace the old commit by a new commit incorporating your1415changes, giving you a chance to edit the old commit message first.14161417Again, you should never do this to a commit that may already have1418been merged into another branch; use gitlink:git-revert[1] instead in1419that case.14201421It is also possible to edit commits further back in the history, but1422this is an advanced topic to be left for1423<<cleaning-up-history,another chapter>>.14241425Checking out an old version of a file1426~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~14271428In the process of undoing a previous bad change, you may find it1429useful to check out an older version of a particular file using1430gitlink:git-checkout[1]. We've used git checkout before to switch1431branches, but it has quite different behavior if it is given a path1432name: the command14331434-------------------------------------------------1435$ git checkout HEAD^ path/to/file1436-------------------------------------------------14371438replaces path/to/file by the contents it had in the commit HEAD^, and1439also updates the index to match. It does not change branches.14401441If you just want to look at an old version of the file, without1442modifying the working directory, you can do that with1443gitlink:git-show[1]:14441445-------------------------------------------------1446$ git show HEAD^ path/to/file1447-------------------------------------------------14481449which will display the given version of the file.14501451Ensuring good performance1452-------------------------14531454On large repositories, git depends on compression to keep the history1455information from taking up to much space on disk or in memory.14561457This compression is not performed automatically. Therefore you1458should occasionally run14591460-------------------------------------------------1461$ git gc1462-------------------------------------------------14631464to recompress the archive and to prune any commits which are no1465longer referred to anywhere. This can be very time-consuming, and1466you should not modify the repository while it is working, so you1467should run it while you are not working.14681469Sharing development with others1470===============================14711472[[getting-updates-with-git-pull]]1473Getting updates with git pull1474-----------------------------14751476After you clone a repository and make a few changes of your own, you1477may wish to check the original repository for updates and merge them1478into your own work.14791480We have already seen <<Updating-a-repository-with-git-fetch,how to1481keep remote tracking branches up to date>> with gitlink:git-fetch[1],1482and how to merge two branches. So you can merge in changes from the1483original repository's master branch with:14841485-------------------------------------------------1486$ git fetch1487$ git merge origin/master1488-------------------------------------------------14891490However, the gitlink:git-pull[1] command provides a way to do this in1491one step:14921493-------------------------------------------------1494$ git pull origin master1495-------------------------------------------------14961497In fact, "origin" is normally the default repository to pull from,1498and the default branch is normally the HEAD of the remote repository,1499so often you can accomplish the above with just15001501-------------------------------------------------1502$ git pull1503-------------------------------------------------15041505See the descriptions of the branch.<name>.remote and1506branch.<name>.merge options in gitlink:git-repo-config[1] to learn1507how to control these defaults depending on the current branch.15081509In addition to saving you keystrokes, "git pull" also helps you by1510producing a default commit message documenting the branch and1511repository that you pulled from.15121513(But note that no such commit will be created in the case of a1514<<fast-forwards,fast forward>>; instead, your branch will just be1515updated to point to the latest commit from the upstream branch).15161517The git-pull command can also be given "." as the "remote" repository, in1518which case it just merges in a branch from the current repository; so1519the commands15201521-------------------------------------------------1522$ git pull . branch1523$ git merge branch1524-------------------------------------------------15251526are roughly equivalent. The former is actually very commonly used.15271528Submitting patches to a project1529-------------------------------15301531If you just have a few changes, the simplest way to submit them may1532just be to send them as patches in email:15331534First, use gitlink:git-format-patches[1]; for example:15351536-------------------------------------------------1537$ git format-patch origin1538-------------------------------------------------15391540will produce a numbered series of files in the current directory, one1541for each patch in the current branch but not in origin/HEAD.15421543You can then import these into your mail client and send them by1544hand. However, if you have a lot to send at once, you may prefer to1545use the gitlink:git-send-email[1] script to automate the process.1546Consult the mailing list for your project first to determine how they1547prefer such patches be handled.15481549Importing patches to a project1550------------------------------15511552Git also provides a tool called gitlink:git-am[1] (am stands for1553"apply mailbox"), for importing such an emailed series of patches.1554Just save all of the patch-containing messages, in order, into a1555single mailbox file, say "patches.mbox", then run15561557-------------------------------------------------1558$ git am -3 patches.mbox1559-------------------------------------------------15601561Git will apply each patch in order; if any conflicts are found, it1562will stop, and you can fix the conflicts as described in1563"<<resolving-a-merge,Resolving a merge>>". (The "-3" option tells1564git to perform a merge; if you would prefer it just to abort and1565leave your tree and index untouched, you may omit that option.)15661567Once the index is updated with the results of the conflict1568resolution, instead of creating a new commit, just run15691570-------------------------------------------------1571$ git am --resolved1572-------------------------------------------------15731574and git will create the commit for you and continue applying the1575remaining patches from the mailbox.15761577The final result will be a series of commits, one for each patch in1578the original mailbox, with authorship and commit log message each1579taken from the message containing each patch.15801581[[setting-up-a-public-repository]]1582Setting up a public repository1583------------------------------15841585Another way to submit changes to a project is to simply tell the1586maintainer of that project to pull from your repository, exactly as1587you did in the section "<<getting-updates-with-git-pull, Getting1588updates with git pull>>".15891590If you and maintainer both have accounts on the same machine, then1591then you can just pull changes from each other's repositories1592directly; note that all of the command (gitlink:git-clone[1],1593git-fetch[1], git-pull[1], etc.) which accept a URL as an argument1594will also accept a local file patch; so, for example, you can1595use15961597-------------------------------------------------1598$ git clone /path/to/repository1599$ git pull /path/to/other/repository1600-------------------------------------------------16011602If this sort of setup is inconvenient or impossible, another (more1603common) option is to set up a public repository on a public server.1604This also allows you to cleanly separate private work in progress1605from publicly visible work.16061607You will continue to do your day-to-day work in your personal1608repository, but periodically "push" changes from your personal1609repository into your public repository, allowing other developers to1610pull from that repository. So the flow of changes, in a situation1611where there is one other developer with a public repository, looks1612like this:16131614 you push1615 your personal repo ------------------> your public repo1616 ^ |1617 | |1618 | you pull | they pull1619 | |1620 | |1621 | they push V1622 their public repo <------------------- their repo16231624Now, assume your personal repository is in the directory ~/proj. We1625first create a new clone of the repository:16261627-------------------------------------------------1628$ git clone --bare proj-clone.git1629-------------------------------------------------16301631The resulting directory proj-clone.git will contains a "bare" git1632repository--it is just the contents of the ".git" directory, without1633a checked-out copy of a working directory.16341635Next, copy proj-clone.git to the server where you plan to host the1636public repository. You can use scp, rsync, or whatever is most1637convenient.16381639If somebody else maintains the public server, they may already have1640set up a git service for you, and you may skip to the section1641"<<pushing-changes-to-a-public-repository,Pushing changes to a public1642repository>>", below.16431644Otherwise, the following sections explain how to export your newly1645created public repository:16461647[[exporting-via-http]]1648Exporting a git repository via http1649-----------------------------------16501651The git protocol gives better performance and reliability, but on a1652host with a web server set up, http exports may be simpler to set up.16531654All you need to do is place the newly created bare git repository in1655a directory that is exported by the web server, and make some1656adjustments to give web clients some extra information they need:16571658-------------------------------------------------1659$ mv proj.git /home/you/public_html/proj.git1660$ cd proj.git1661$ git update-server-info1662$ chmod a+x hooks/post-update1663-------------------------------------------------16641665(For an explanation of the last two lines, see1666gitlink:git-update-server-info[1], and the documentation1667link:hooks.txt[Hooks used by git].)16681669Advertise the url of proj.git. Anybody else should then be able to1670clone or pull from that url, for example with a commandline like:16711672-------------------------------------------------1673$ git clone http://yourserver.com/~you/proj.git1674-------------------------------------------------16751676(See also1677link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]1678for a slightly more sophisticated setup using WebDAV which also1679allows pushing over http.)16801681[[exporting-via-git]]1682Exporting a git repository via the git protocol1683-----------------------------------------------16841685This is the preferred method.16861687For now, we refer you to the gitlink:git-daemon[1] man page for1688instructions. (See especially the examples section.)16891690[[pushing-changes-to-a-public-repository]]1691Pushing changes to a public repository1692--------------------------------------16931694Note that the two techniques outline above (exporting via1695<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other1696maintainers to fetch your latest changes, but they do not allow write1697access, which you will need to update the public repository with the1698latest changes created in your private repository.16991700The simplest way to do this is using gitlink:git-push[1] and ssh; to1701update the remote branch named "master" with the latest state of your1702branch named "master", run17031704-------------------------------------------------1705$ git push ssh://yourserver.com/~you/proj.git master:master1706-------------------------------------------------17071708or just17091710-------------------------------------------------1711$ git push ssh://yourserver.com/~you/proj.git master1712-------------------------------------------------17131714As with git-fetch, git-push will complain if this does not result in1715a <<fast-forwards,fast forward>>. Normally this is a sign of1716something wrong. However, if you are sure you know what you're1717doing, you may force git-push to perform the update anyway by1718proceeding the branch name by a plus sign:17191720-------------------------------------------------1721$ git push ssh://yourserver.com/~you/proj.git +master1722-------------------------------------------------17231724As with git-fetch, you may also set up configuration options to1725save typing; so, for example, after17261727-------------------------------------------------1728$ cat >.git/config <<EOF1729[remote "public-repo"]1730 url = ssh://yourserver.com/~you/proj.git1731EOF1732-------------------------------------------------17331734you should be able to perform the above push with just17351736-------------------------------------------------1737$ git push public-repo master1738-------------------------------------------------17391740See the explanations of the remote.<name>.url, branch.<name>.remote,1741and remote.<name>.push options in gitlink:git-repo-config[1] for1742details.17431744Setting up a shared repository1745------------------------------17461747Another way to collaborate is by using a model similar to that1748commonly used in CVS, where several developers with special rights1749all push to and pull from a single shared repository. See1750link:cvs-migration.txt[git for CVS users] for instructions on how to1751set this up.17521753Allow web browsing of a repository1754----------------------------------17551756TODO: Brief setup-instructions for gitweb17571758Examples1759--------17601761TODO: topic branches, typical roles as in everyday.txt, ?176217631764Working with other version control systems1765==========================================17661767TODO: CVS, Subversion, series-of-release-tarballs, ?17681769[[cleaning-up-history]]1770Rewriting history and maintaining patch series1771==============================================17721773Normally commits are only added to a project, never taken away or1774replaced. Git is designed with this assumption, and violating it will1775cause git's merge machinery (for example) to do the wrong thing.17761777However, there is a situation in which it can be useful to violate this1778assumption.17791780Creating the perfect patch series1781---------------------------------17821783Suppose you are a contributor to a large project, and you want to add a1784complicated feature, and to present it to the other developers in a way1785that makes it easy for them to read your changes, verify that they are1786correct, and understand why you made each change.17871788If you present all of your changes as a single patch (or commit), they may1789find it is too much to digest all at once.17901791If you present them with the entire history of your work, complete with1792mistakes, corrections, and dead ends, they may be overwhelmed.17931794So the ideal is usually to produce a series of patches such that:17951796 1. Each patch can be applied in order.17971798 2. Each patch includes a single logical change, together with a1799 message explaining the change.18001801 3. No patch introduces a regression: after applying any initial1802 part of the series, the resulting project still compiles and1803 works, and has no bugs that it didn't have before.18041805 4. The complete series produces the same end result as your own1806 (probably much messier!) development process did.18071808We will introduce some tools that can help you do this, explain how to use1809them, and then explain some of the problems that can arise because you are1810rewriting history.18111812Keeping a patch series up to date using git-rebase1813--------------------------------------------------18141815Suppose you have a series of commits in a branch "mywork", which1816originally branched off from "origin".18171818Suppose you create a branch "mywork" on a remote-tracking branch "origin",1819and created some commits on top of it:18201821-------------------------------------------------1822$ git checkout -b mywork origin1823$ vi file.txt1824$ git commit1825$ vi otherfile.txt1826$ git commit1827...1828-------------------------------------------------18291830You have performed no merges into mywork, so it is just a simple linear1831sequence of patches on top of "origin":183218331834 o--o--o <-- origin1835 \1836 o--o--o <-- mywork18371838Some more interesting work has been done in the upstream project, and1839"origin" has advanced:18401841 o--o--O--o--o--o <-- origin1842 \1843 a--b--c <-- mywork18441845At this point, you could use "pull" to merge your changes back in;1846the result would create a new merge commit, like this:184718481849 o--o--O--o--o--o <-- origin1850 \ \1851 a--b--c--m <-- mywork18521853However, if you prefer to keep the history in mywork a simple series of1854commits without any merges, you may instead choose to use1855gitlink:git-rebase[1]:18561857-------------------------------------------------1858$ git checkout mywork1859$ git rebase origin1860-------------------------------------------------18611862This will remove each of your commits from mywork, temporarily saving them1863as patches (in a directory named ".dotest"), update mywork to point at the1864latest version of origin, then apply each of the saved patches to the new1865mywork. The result will look like:186618671868 o--o--O--o--o--o <-- origin1869 \1870 a'--b'--c' <-- mywork18711872In the process, it may discover conflicts. In that case it will stop and1873allow you to fix the conflicts as described in1874"<<resolving-a-merge,Resolving a merge>>".18751876XXX: no, maybe not: git diff doesn't produce very useful results, and there's1877no MERGE_HEAD.18781879Once the index is updated with1880the results of the conflict resolution, instead of creating a new commit,1881just run18821883-------------------------------------------------1884$ git rebase --continue1885-------------------------------------------------18861887and git will continue applying the rest of the patches.18881889At any point you may use the --abort option to abort this process and1890return mywork to the state it had before you started the rebase:18911892-------------------------------------------------1893$ git rebase --abort1894-------------------------------------------------18951896Reordering or selecting from a patch series1897-------------------------------------------18981899Given one existing commit, the gitlink:git-cherry-pick[1] command allows1900you to apply the change introduced by that commit and create a new commit1901that records it.19021903This can be useful for modifying a patch series.19041905TODO: elaborate19061907Other tools1908-----------19091910There are numerous other tools, such as stgit, which exist for the purpose1911of maintianing a patch series. These are out of the scope of this manual.19121913Problems with rewriting history1914-------------------------------19151916The primary problem with rewriting the history of a branch has to do with1917merging.19181919TODO: elaborate192019211922Git internals1923=============19241925Architectural overview1926----------------------19271928TODO: Sources, README, core-tutorial, tutorial-2.txt, technical/19291930Glossary of git terms1931=====================19321933include::glossary.txt[]19341935Notes and todo list for this manual1936===================================19371938This is a work in progress.19391940The basic requirements:1941 - It must be readable in order, from beginning to end, by1942 someone intelligent with a basic grasp of the unix1943 commandline, but without any special knowledge of git. If1944 necessary, any other prerequisites should be specifically1945 mentioned as they arise.1946 - Whenever possible, section headings should clearly describe1947 the task they explain how to do, in language that requires1948 no more knowledge than necessary: for example, "importing1949 patches into a project" rather than "the git-am command"19501951Think about how to create a clear chapter dependency graph that will1952allow people to get to important topics without necessarily reading1953everything in between.19541955Scan Documentation/ for other stuff left out; in particular:1956 howto's1957 README1958 some of technical/?1959 hooks1960 etc.19611962Scan email archives for other stuff left out19631964Scan man pages to see if any assume more background than this manual1965provides.19661967Simplify beginning by suggesting disconnected head instead of1968temporary branch creation.19691970Explain how to refer to file stages in the "how to resolve a merge"1971section: diff -1, -2, -3, --ours, --theirs :1:/path notation. The1972"git ls-files --unmerged --stage" thing is sorta useful too,1973actually. And note gitk --merge. Also what's easiest way to see1974common merge base? Note also text where I claim rebase and am1975conflicts are resolved like merges isn't generally true, at least by1976default--fix.19771978Add more good examples. Entire sections of just cookbook examples1979might be a good idea; maybe make an "advanced examples" section a1980standard end-of-chapter section?19811982Include cross-references to the glossary, where appropriate.19831984Add quickstart as first chapter.19851986To document:1987 reflogs, git reflog expire1988 shallow clones?? See draft 1.5.0 release notes for some documentation.