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 307Create a new branch pointing to one of these versions and check it 308out using gitlink:git-checkout[1]: 309 310------------------------------------------------ 311$ git checkout -b new v2.6.13 312------------------------------------------------ 313 314The working directory then reflects the contents that the project had 315when it was tagged v2.6.13, and gitlink:git-branch[1] shows two 316branches, with an asterisk marking the currently checked-out branch: 317 318------------------------------------------------ 319$ git branch 320 master 321* new 322------------------------------------------------ 323 324If you decide that you'd rather see version 2.6.17, you can modify 325the current branch to point at v2.6.17 instead, with 326 327------------------------------------------------ 328$ git reset --hard v2.6.17 329------------------------------------------------ 330 331Note that if the current branch was your only reference to a 332particular point in history, then resetting that branch may leave you 333with no way to find the history it used to point to; so use this 334command carefully. 335 336Understanding History: Commits 337------------------------------ 338 339Every change in the history of a project is represented by a commit. 340The gitlink:git-show[1] command shows the most recent commit on the 341current branch: 342 343------------------------------------------------ 344$ git show 345commit 2b5f6dcce5bf94b9b119e9ed8d537098ec61c3d2 346Author: Jamal Hadi Salim <hadi@cyberus.ca> 347Date: Sat Dec 2 22:22:25 2006 -0800 348 349 [XFRM]: Fix aevent structuring to be more complete. 350 351 aevents can not uniquely identify an SA. We break the ABI with this 352 patch, but consensus is that since it is not yet utilized by any 353 (known) application then it is fine (better do it now than later). 354 355 Signed-off-by: Jamal Hadi Salim <hadi@cyberus.ca> 356 Signed-off-by: David S. Miller <davem@davemloft.net> 357 358diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt 359index 8be626f..d7aac9d 100644 360--- a/Documentation/networking/xfrm_sync.txt 361+++ b/Documentation/networking/xfrm_sync.txt 362@@ -47,10 +47,13 @@ aevent_id structure looks like: 363 364 struct xfrm_aevent_id { 365 struct xfrm_usersa_id sa_id; 366+ xfrm_address_t saddr; 367 __u32 flags; 368+ __u32 reqid; 369 }; 370... 371------------------------------------------------ 372 373As you can see, a commit shows who made the latest change, what they 374did, and why. 375 376Every commit has a 40-hexdigit id, sometimes called the "SHA1 id", shown 377on the first line of the "git show" output. You can usually refer to 378a commit by a shorter name, such as a tag or a branch name, but this 379longer id can also be useful. In particular, it is a globally unique 380name for this commit: so if you tell somebody else the SHA1 id (for 381example in email), then you are guaranteed they will see the same 382commit in their repository that you do in yours. 383 384Understanding history: commits, parents, and reachability 385~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 386 387Every commit (except the very first commit in a project) also has a 388parent commit which shows what happened before this commit. 389Following the chain of parents will eventually take you back to the 390beginning of the project. 391 392However, the commits do not form a simple list; git allows lines of 393development to diverge and then reconverge, and the point where two 394lines of development reconverge is called a "merge". The commit 395representing a merge can therefore have more than one parent, with 396each parent representing the most recent commit on one of the lines 397of development leading to that point. 398 399The best way to see how this works is using the gitlink:gitk[1] 400command; running gitk now on a git repository and looking for merge 401commits will help understand how the git organizes history. 402 403In the following, we say that commit X is "reachable" from commit Y 404if commit X is an ancestor of commit Y. Equivalently, you could say 405that Y is a descendent of X, or that there is a chain of parents 406leading from commit Y to commit X. 407 408Undestanding history: History diagrams 409~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 410 411We will sometimes represent git history using diagrams like the one 412below. Commits are shown as "o", and the links between them with 413lines drawn with - / and \. Time goes left to right: 414 415 o--o--o <-- Branch A 416 / 417 o--o--o <-- master 418 \ 419 o--o--o <-- Branch B 420 421If we need to talk about a particular commit, the character "o" may 422be replaced with another letter or number. 423 424Understanding history: What is a branch? 425~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 426 427Though we've been using the word "branch" to mean a kind of reference 428to a particular commit, the word branch is also commonly used to 429refer to the line of commits leading up to that point. In the 430example above, git may think of the branch named "A" as just a 431pointer to one particular commit, but we may refer informally to the 432line of three commits leading up to that point as all being part of 433"branch A". 434 435If we need to make it clear that we're just talking about the most 436recent commit on the branch, we may refer to that commit as the 437"head" of the branch. 438 439Manipulating branches 440--------------------- 441 442Creating, deleting, and modifying branches is quick and easy; here's 443a summary of the commands: 444 445git branch:: 446 list all branches 447git branch <branch>:: 448 create a new branch named <branch>, referencing the same 449 point in history as the current branch 450git branch <branch> <start-point>:: 451 create a new branch named <branch>, referencing 452 <start-point>, which may be specified any way you like, 453 including using a branch name or a tag name 454git branch -d <branch>:: 455 delete the branch <branch>; if the branch you are deleting 456 points to a commit which is not reachable from this branch, 457 this command will fail with a warning. 458git branch -D <branch>:: 459 even if the branch points to a commit not reachable 460 from the current branch, you may know that that commit 461 is still reachable from some other branch or tag. In that 462 case it is safe to use this command to force git to delete 463 the branch. 464git checkout <branch>:: 465 make the current branch <branch>, updating the working 466 directory to reflect the version referenced by <branch> 467git checkout -b <new> <start-point>:: 468 create a new branch <new> referencing <start-point>, and 469 check it out. 470 471It is also useful to know that the special symbol "HEAD" can always 472be used to refer to the current branch. 473 474Examining branches from a remote repository 475------------------------------------------- 476 477The "master" branch that was created at the time you cloned is a copy 478of the HEAD in the repository that you cloned from. That repository 479may also have had other branches, though, and your local repository 480keeps branches which track each of those remote branches, which you 481can view using the "-r" option to gitlink:git-branch[1]: 482 483------------------------------------------------ 484$ git branch -r 485 origin/HEAD 486 origin/html 487 origin/maint 488 origin/man 489 origin/master 490 origin/next 491 origin/pu 492 origin/todo 493------------------------------------------------ 494 495You cannot check out these remote-tracking branches, but you can 496examine them on a branch of your own, just as you would a tag: 497 498------------------------------------------------ 499$ git checkout -b my-todo-copy origin/todo 500------------------------------------------------ 501 502Note that the name "origin" is just the name that git uses by default 503to refer to the repository that you cloned from. 504 505[[how-git-stores-references]] 506How git stores references 507------------------------- 508 509Branches, remote-tracking branches, and tags are all references to 510commits. Git stores these references in the ".git" directory. Most 511of them are stored in .git/refs/: 512 513 - branches are stored in .git/refs/heads 514 - tags are stored in .git/refs/tags 515 - remote-tracking branches for "origin" are stored in 516 .git/refs/remotes/origin/ 517 518If you look at one of these files you will see that they usually 519contain just the SHA1 id of a commit: 520 521------------------------------------------------ 522$ ls .git/refs/heads/ 523master 524$ cat .git/refs/heads/master 525c0f982dcf188d55db9d932a39d4ea7becaa55fed 526------------------------------------------------ 527 528You can refer to a reference by its path relative to the .git 529directory. However, we've seen above that git will also accept 530shorter names; for example, "master" is an acceptable shortcut for 531"refs/heads/master", and "origin/master" is a shortcut for 532"refs/remotes/origin/master". 533 534As another useful shortcut, you can also refer to the "HEAD" of 535"origin" (or any other remote), using just the name of the remote. 536 537For the complete list of paths which git checks for references, and 538how it decides which to choose when there are multiple references 539with the same name, see the "SPECIFYING REVISIONS" section of 540gitlink:git-rev-parse[1]. 541 542[[Updating-a-repository-with-git-fetch]] 543Updating a repository with git fetch 544------------------------------------ 545 546Eventually the developer cloned from will do additional work in her 547repository, creating new commits and advancing the branches to point 548at the new commits. 549 550The command "git fetch", with no arguments, will update all of the 551remote-tracking branches to the latest version found in her 552repository. It will not touch any of your own branches--not even the 553"master" branch that was created for you on clone. 554 555Fetching branches from other repositories 556----------------------------------------- 557 558You can also track branches from repositories other than the one you 559cloned from, using gitlink:git-remote[1]: 560 561------------------------------------------------- 562$ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git 563$ git fetch 564* refs/remotes/linux-nfs/master: storing branch 'master' ... 565 commit: bf81b46 566------------------------------------------------- 567 568New remote-tracking branches will be stored under the shorthand name 569that you gave "git remote add", in this case linux-nfs: 570 571------------------------------------------------- 572$ git branch -r 573linux-nfs/master 574origin/master 575------------------------------------------------- 576 577If you run "git fetch <remote>" later, the tracking branches for the 578named <remote> will be updated. 579 580If you examine the file .git/config, you will see that git has added 581a new stanza: 582 583------------------------------------------------- 584$ cat .git/config 585... 586[remote "linux-nfs"] 587 url = git://linux-nfs.org/~bfields/git.git 588 fetch = +refs/heads/*:refs/remotes/linux-nfs-read/* 589... 590------------------------------------------------- 591 592This is what causes git to track the remote's branches; you may 593modify or delete these configuration options by editing .git/config 594with a text editor. 595 596Fetching individual branches 597---------------------------- 598 599TODO: find another home for this, later on: 600 601You can also choose to update just one branch at a time: 602 603------------------------------------------------- 604$ git fetch origin todo:refs/remotes/origin/todo 605------------------------------------------------- 606 607The first argument, "origin", just tells git to fetch from the 608repository you originally cloned from. The second argument tells git 609to fetch the branch named "todo" from the remote repository, and to 610store it locally under the name refs/remotes/origin/todo; as we saw 611above, remote-tracking branches are stored under 612refs/remotes/<name-of-repository>/<name-of-branch>. 613 614You can also fetch branches from other repositories; so 615 616------------------------------------------------- 617$ git fetch git://example.com/proj.git master:refs/remotes/example/master 618------------------------------------------------- 619 620will create a new reference named "refs/remotes/example/master" and 621store in it the branch named "master" from the repository at the 622given URL. If you already have a branch named 623"refs/remotes/example/master", it will attempt to "fast-forward" to 624the commit given by example.com's master branch. So next we explain 625what a fast-forward is: 626 627[[fast-forwards]] 628Understanding git history: fast-forwards 629---------------------------------------- 630 631In the previous example, when updating an existing branch, "git 632fetch" checks to make sure that the most recent commit on the remote 633branch is a descendant of the most recent commit on your copy of the 634branch before updating your copy of the branch to point at the new 635commit. Git calls this process a "fast forward". 636 637A fast forward looks something like this: 638 639 o--o--o--o <-- old head of the branch 640 \ 641 o--o--o <-- new head of the branch 642 643 644In some cases it is possible that the new head will *not* actually be 645a descendant of the old head. For example, the developer may have 646realized she made a serious mistake, and decided to backtrack, 647resulting in a situation like: 648 649 o--o--o--o--a--b <-- old head of the branch 650 \ 651 o--o--o <-- new head of the branch 652 653 654 655In this case, "git fetch" will fail, and print out a warning. 656 657In that case, you can still force git to update to the new head, as 658described in the following section. However, note that in the 659situation above this may mean losing the commits labeled "a" and "b", 660unless you've already created a reference of your own pointing to 661them. 662 663Forcing git fetch to do non-fast-forward updates 664------------------------------------------------ 665 666If git fetch fails because the new head of a branch is not a 667descendant of the old head, you may force the update with: 668 669------------------------------------------------- 670$ git fetch git://example.com/proj.git +master:refs/remotes/example/master 671------------------------------------------------- 672 673Note the addition of the "+" sign. Be aware that commits which the 674old version of example/master pointed at may be lost, as we saw in 675the previous section. 676 677Configuring remote branches 678--------------------------- 679 680We saw above that "origin" is just a shortcut to refer to the 681repository which you originally cloned from. This information is 682stored in git configuration variables, which you can see using 683gitlink:git-repo-config[1]: 684 685------------------------------------------------- 686$ git-repo-config -l 687core.repositoryformatversion=0 688core.filemode=true 689core.logallrefupdates=true 690remote.origin.url=git://git.kernel.org/pub/scm/git/git.git 691remote.origin.fetch=+refs/heads/*:refs/remotes/origin/* 692branch.master.remote=origin 693branch.master.merge=refs/heads/master 694------------------------------------------------- 695 696If there are other repositories that you also use frequently, you can 697create similar configuration options to save typing; for example, 698after 699 700------------------------------------------------- 701$ git repo-config remote.example.url git://example.com/proj.git 702------------------------------------------------- 703 704then the following two commands will do the same thing: 705 706------------------------------------------------- 707$ git fetch git://example.com/proj.git master:refs/remotes/example/master 708$ git fetch example master:refs/remotes/example/master 709------------------------------------------------- 710 711Even better, if you add one more option: 712 713------------------------------------------------- 714$ git repo-config remote.example.fetch master:refs/remotes/example/master 715------------------------------------------------- 716 717then the following commands will all do the same thing: 718 719------------------------------------------------- 720$ git fetch git://example.com/proj.git master:ref/remotes/example/master 721$ git fetch example master:ref/remotes/example/master 722$ git fetch example example/master 723$ git fetch example 724------------------------------------------------- 725 726You can also add a "+" to force the update each time: 727 728------------------------------------------------- 729$ git repo-config remote.example.fetch +master:ref/remotes/example/master 730------------------------------------------------- 731 732Don't do this unless you're sure you won't mind "git fetch" possibly 733throwing away commits on mybranch. 734 735Also note that all of the above configuration can be performed by 736directly editing the file .git/config instead of using 737gitlink:git-repo-config[1]. 738 739See gitlink:git-repo-config[1] for more details on the configuration 740options mentioned above. 741 742Exploring git history 743===================== 744 745Git is best thought of as a tool for storing the history of a 746collection of files. It does this by storing compressed snapshots of 747the contents of a file heirarchy, together with "commits" which show 748the relationships between these snapshots. 749 750Git provides extremely flexible and fast tools for exploring the 751history of a project. 752 753We start with one specialized tool which is useful for finding the 754commit that introduced a bug into a project. 755 756How to use bisect to find a regression 757-------------------------------------- 758 759Suppose version 2.6.18 of your project worked, but the version at 760"master" crashes. Sometimes the best way to find the cause of such a 761regression is to perform a brute-force search through the project's 762history to find the particular commit that caused the problem. The 763gitlink:git-bisect[1] command can help you do this: 764 765------------------------------------------------- 766$ git bisect start 767$ git bisect good v2.6.18 768$ git bisect bad master 769Bisecting: 3537 revisions left to test after this 770[65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6] 771------------------------------------------------- 772 773If you run "git branch" at this point, you'll see that git has 774temporarily moved you to a new branch named "bisect". This branch 775points to a commit (with commit id 65934...) that is reachable from 776v2.6.19 but not from v2.6.18. Compile and test it, and see whether 777it crashes. Assume it does crash. Then: 778 779------------------------------------------------- 780$ git bisect bad 781Bisecting: 1769 revisions left to test after this 782[7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings 783------------------------------------------------- 784 785checks out an older version. Continue like this, telling git at each 786stage whether the version it gives you is good or bad, and notice 787that the number of revisions left to test is cut approximately in 788half each time. 789 790After about 13 tests (in this case), it will output the commit id of 791the guilty commit. You can then examine the commit with 792gitlink:git-show[1], find out who wrote it, and mail them your bug 793report with the commit id. Finally, run 794 795------------------------------------------------- 796$ git bisect reset 797------------------------------------------------- 798 799to return you to the branch you were on before and delete the 800temporary "bisect" branch. 801 802Note that the version which git-bisect checks out for you at each 803point is just a suggestion, and you're free to try a different 804version if you think it would be a good idea. For example, 805occasionally you may land on a commit that broke something unrelated; 806run 807 808------------------------------------------------- 809$ git bisect-visualize 810------------------------------------------------- 811 812which will run gitk and label the commit it chose with a marker that 813says "bisect". Chose a safe-looking commit nearby, note its commit 814id, and check it out with: 815 816------------------------------------------------- 817$ git reset --hard fb47ddb2db... 818------------------------------------------------- 819 820then test, run "bisect good" or "bisect bad" as appropriate, and 821continue. 822 823Naming commits 824-------------- 825 826We have seen several ways of naming commits already: 827 828 - 40-hexdigit SHA1 id 829 - branch name: refers to the commit at the head of the given 830 branch 831 - tag name: refers to the commit pointed to by the given tag 832 (we've seen branches and tags are special cases of 833 <<how-git-stores-references,references>>). 834 - HEAD: refers to the head of the current branch 835 836There are many more; see the "SPECIFYING REVISIONS" section of the 837gitlink:git-rev-parse[1] man page for the complete list of ways to 838name revisions. Some examples: 839 840------------------------------------------------- 841$ git show fb47ddb2 # the first few characters of the SHA1 id 842 # are usually enough to specify it uniquely 843$ git show HEAD^ # the parent of the HEAD commit 844$ git show HEAD^^ # the grandparent 845$ git show HEAD~4 # the great-great-grandparent 846------------------------------------------------- 847 848Recall that merge commits may have more than one parent; by default, 849^ and ~ follow the first parent listed in the commit, but you can 850also choose: 851 852------------------------------------------------- 853$ git show HEAD^1 # show the first parent of HEAD 854$ git show HEAD^2 # show the second parent of HEAD 855------------------------------------------------- 856 857In addition to HEAD, there are several other special names for 858commits: 859 860Merges (to be discussed later), as well as operations such as 861git-reset, which change the currently checked-out commit, generally 862set ORIG_HEAD to the value HEAD had before the current operation. 863 864The git-fetch operation always stores the head of the last fetched 865branch in FETCH_HEAD. For example, if you run git fetch without 866specifying a local branch as the target of the operation 867 868------------------------------------------------- 869$ git fetch git://example.com/proj.git theirbranch 870------------------------------------------------- 871 872the fetched commits will still be available from FETCH_HEAD. 873 874When we discuss merges we'll also see the special name MERGE_HEAD, 875which refers to the other branch that we're merging in to the current 876branch. 877 878The gitlink:git-rev-parse[1] command is a low-level command that is 879occasionally useful for translating some name for a commit to the SHA1 id for 880that commit: 881 882------------------------------------------------- 883$ git rev-parse origin 884e05db0fd4f31dde7005f075a84f96b360d05984b 885------------------------------------------------- 886 887Creating tags 888------------- 889 890We can also create a tag to refer to a particular commit; after 891running 892 893------------------------------------------------- 894$ git-tag stable-1 1b2e1d63ff 895------------------------------------------------- 896 897You can use stable-1 to refer to the commit 1b2e1d63ff. 898 899This creates a "lightweight" tag. If the tag is a tag you wish to 900share with others, and possibly sign cryptographically, then you 901should create a tag object instead; see the gitlink:git-tag[1] man 902page for details. 903 904Browsing revisions 905------------------ 906 907The gitlink:git-log[1] command can show lists of commits. On its 908own, it shows all commits reachable from the parent commit; but you 909can also make more specific requests: 910 911------------------------------------------------- 912$ git log v2.5.. # commits since (not reachable from) v2.5 913$ git log test..master # commits reachable from master but not test 914$ git log master..test # ...reachable from test but not master 915$ git log master...test # ...reachable from either test or master, 916 # but not both 917$ git log --since="2 weeks ago" # commits from the last 2 weeks 918$ git log Makefile # commits which modify Makefile 919$ git log fs/ # ... which modify any file under fs/ 920$ git log -S'foo()' # commits which add or remove any file data 921 # matching the string 'foo()' 922------------------------------------------------- 923 924And of course you can combine all of these; the following finds 925commits since v2.5 which touch the Makefile or any file under fs: 926 927------------------------------------------------- 928$ git log v2.5.. Makefile fs/ 929------------------------------------------------- 930 931You can also ask git log to show patches: 932 933------------------------------------------------- 934$ git log -p 935------------------------------------------------- 936 937See the "--pretty" option in the gitlink:git-log[1] man page for more 938display options. 939 940Note that git log starts with the most recent commit and works 941backwards through the parents; however, since git history can contain 942multiple independant lines of development, the particular order that 943commits are listed in may be somewhat arbitrary. 944 945Generating diffs 946---------------- 947 948You can generate diffs between any two versions using 949gitlink:git-diff[1]: 950 951------------------------------------------------- 952$ git diff master..test 953------------------------------------------------- 954 955Sometimes what you want instead is a set of patches: 956 957------------------------------------------------- 958$ git format-patch master..test 959------------------------------------------------- 960 961will generate a file with a patch for each commit reachable from test 962but not from master. Note that if master also has commits which are 963not reachable from test, then the combined result of these patches 964will not be the same as the diff produced by the git-diff example. 965 966Viewing old file versions 967------------------------- 968 969You can always view an old version of a file by just checking out the 970correct revision first. But sometimes it is more convenient to be 971able to view an old version of a single file without checking 972anything out; this command does that: 973 974------------------------------------------------- 975$ git show v2.5:fs/locks.c 976------------------------------------------------- 977 978Before the colon may be anything that names a commit, and after it 979may be any path to a file tracked by git. 980 981Examples 982-------- 983 984Check whether two branches point at the same history 985~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 986 987Suppose you want to check whether two branches point at the same point 988in history. 989 990------------------------------------------------- 991$ git diff origin..master 992------------------------------------------------- 993 994will tell you whether the contents of the project are the same at the 995two branches; in theory, however, it's possible that the same project 996contents could have been arrived at by two different historical 997routes. You could compare the SHA1 id's: 998 999-------------------------------------------------1000$ git rev-list origin1001e05db0fd4f31dde7005f075a84f96b360d05984b1002$ git rev-list master1003e05db0fd4f31dde7005f075a84f96b360d05984b1004-------------------------------------------------10051006Or you could recall that the ... operator selects all commits1007contained reachable from either one reference or the other but not1008both: so10091010-------------------------------------------------1011$ git log origin...master1012-------------------------------------------------10131014will return no commits when the two branches are equal.10151016Check which tagged version a given fix was first included in1017~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~10181019Suppose you know that the commit e05db0fd fixed a certain problem.1020You'd like to find the earliest tagged release that contains that1021fix.10221023Of course, there may be more than one answer--if the history branched1024after commit e05db0fd, then there could be multiple "earliest" tagged1025releases.10261027You could just visually inspect the commits since e05db0fd:10281029-------------------------------------------------1030$ gitk e05db0fd..1031-------------------------------------------------10321033...10341035Developing with git1036===================10371038Telling git your name1039---------------------10401041Before creating any commits, you should introduce yourself to git. The1042easiest way to do so is:10431044------------------------------------------------1045$ cat >~/.gitconfig <<\EOF1046[user]1047 name = Your Name Comes Here1048 email = you@yourdomain.example.com1049EOF1050------------------------------------------------105110521053Creating a new repository1054-------------------------10551056Creating a new repository from scratch is very easy:10571058-------------------------------------------------1059$ mkdir project1060$ cd project1061$ git init1062-------------------------------------------------10631064If you have some initial content (say, a tarball):10651066-------------------------------------------------1067$ tar -xzvf project.tar.gz1068$ cd project1069$ git init1070$ git add . # include everything below ./ in the first commit:1071$ git commit1072-------------------------------------------------10731074[[how-to-make-a-commit]]1075how to make a commit1076--------------------10771078Creating a new commit takes three steps:10791080 1. Making some changes to the working directory using your1081 favorite editor.1082 2. Telling git about your changes.1083 3. Creating the commit using the content you told git about1084 in step 2.10851086In practice, you can interleave and repeat steps 1 and 2 as many1087times as you want: in order to keep track of what you want committed1088at step 3, git maintains a snapshot of the tree's contents in a1089special staging area called "the index."10901091At the beginning, the content of the index will be identical to1092that of the HEAD. The command "git diff --cached", which shows1093the difference between the HEAD and the index, should therefore1094produce no output at that point.10951096Modifying the index is easy:10971098To update the index with the new contents of a modified file, use10991100-------------------------------------------------1101$ git add path/to/file1102-------------------------------------------------11031104To add the contents of a new file to the index, use11051106-------------------------------------------------1107$ git add path/to/file1108-------------------------------------------------11091110To remove a file from the index and from the working tree,11111112-------------------------------------------------1113$ git rm path/to/file1114-------------------------------------------------11151116After each step you can verify that11171118-------------------------------------------------1119$ git diff --cached1120-------------------------------------------------11211122always shows the difference between the HEAD and the index file--this1123is what you'd commit if you created the commit now--and that11241125-------------------------------------------------1126$ git diff1127-------------------------------------------------11281129shows the difference between the working tree and the index file.11301131Note that "git add" always adds just the current contents of a file1132to the index; further changes to the same file will be ignored unless1133you run git-add on the file again.11341135When you're ready, just run11361137-------------------------------------------------1138$ git commit1139-------------------------------------------------11401141and git will prompt you for a commit message and then create the new1142commmit. Check to make sure it looks like what you expected with11431144-------------------------------------------------1145$ git show1146-------------------------------------------------11471148As a special shortcut,11491150-------------------------------------------------1151$ git commit -a1152-------------------------------------------------11531154will update the index with any files that you've modified or removed1155and create a commit, all in one step.11561157A number of commands are useful for keeping track of what you're1158about to commit:11591160-------------------------------------------------1161$ git diff --cached # difference between HEAD and the index; what1162 # would be commited if you ran "commit" now.1163$ git diff # difference between the index file and your1164 # working directory; changes that would not1165 # be included if you ran "commit" now.1166$ git status # a brief per-file summary of the above.1167-------------------------------------------------11681169creating good commit messages1170-----------------------------11711172Though not required, it's a good idea to begin the commit message1173with a single short (less than 50 character) line summarizing the1174change, followed by a blank line and then a more thorough1175description. Tools that turn commits into email, for example, use1176the first line on the Subject line and the rest of the commit in the1177body.11781179how to merge1180------------11811182You can rejoin two diverging branches of development using1183gitlink:git-merge[1]:11841185-------------------------------------------------1186$ git merge branchname1187-------------------------------------------------11881189merges the development in the branch "branchname" into the current1190branch. If there are conflicts--for example, if the same file is1191modified in two different ways in the remote branch and the local1192branch--then you are warned; the output may look something like this:11931194-------------------------------------------------1195$ git pull . next1196Trying really trivial in-index merge...1197fatal: Merge requires file-level merging1198Nope.1199Merging HEAD with 77976da35a11db4580b80ae27e8d65caf52080861200Merging:120115e2162 world120277976da goodbye1203found 1 common ancestor(s):1204d122ed4 initial1205Auto-merging file.txt1206CONFLICT (content): Merge conflict in file.txt1207Automatic merge failed; fix conflicts and then commit the result.1208-------------------------------------------------12091210Conflict markers are left in the problematic files, and after1211you resolve the conflicts manually, you can update the index1212with the contents and run git commit, as you normally would when1213creating a new file.12141215If you examine the resulting commit using gitk, you will see that it1216has two parents, one pointing to the top of the current branch, and1217one to the top of the other branch.12181219In more detail:12201221[[resolving-a-merge]]1222Resolving a merge1223-----------------12241225When a merge isn't resolved automatically, git leaves the index and1226the working tree in a special state that gives you all the1227information you need to help resolve the merge.12281229Files with conflicts are marked specially in the index, so until you1230resolve the problem and update the index, git commit will fail:12311232-------------------------------------------------1233$ git commit1234file.txt: needs merge1235-------------------------------------------------12361237Also, git status will list those files as "unmerged".12381239All of the changes that git was able to merge automatically are1240already added to the index file, so gitlink:git-diff[1] shows only1241the conflicts. Also, it uses a somewhat unusual syntax:12421243-------------------------------------------------1244$ git diff1245diff --cc file.txt1246index 802992c,2b60207..00000001247--- a/file.txt1248+++ b/file.txt1249@@@ -1,1 -1,1 +1,5 @@@1250++<<<<<<< HEAD:file.txt1251 +Hello world1252++=======1253+ Goodbye1254++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt1255-------------------------------------------------12561257Recall that the commit which will be commited after we resolve this1258conflict will have two parents instead of the usual one: one parent1259will be HEAD, the tip of the current branch; the other will be the1260tip of the other branch, which is stored temporarily in MERGE_HEAD.12611262The diff above shows the differences between the working-tree version1263of file.txt and two previous version: one version from HEAD, and one1264from MERGE_HEAD. So instead of preceding each line by a single "+"1265or "-", it now uses two columns: the first column is used for1266differences between the first parent and the working directory copy,1267and the second for differences between the second parent and the1268working directory copy. Thus after resolving the conflict in the1269obvious way, the diff will look like:12701271-------------------------------------------------1272$ git diff1273diff --cc file.txt1274index 802992c,2b60207..00000001275--- a/file.txt1276+++ b/file.txt1277@@@ -1,1 -1,1 +1,1 @@@1278- Hello world1279 -Goodbye1280++Goodbye world1281-------------------------------------------------12821283This shows that our resolved version deleted "Hello world" from the1284first parent, deleted "Goodbye" from the second parent, and added1285"Goodbye world", which was previously absent from both.12861287The gitlink:git-log[1] command also provides special help for merges:12881289-------------------------------------------------1290$ git log --merge1291-------------------------------------------------12921293This will list all commits which exist only on HEAD or on MERGE_HEAD,1294and which touch an unmerged file.12951296We can now add the resolved version to the index and commit:12971298-------------------------------------------------1299$ git add file.txt1300$ git commit1301-------------------------------------------------13021303Note that the commit message will already be filled in for you with1304some information about the merge. Normally you can just use this1305default message unchanged, but you may add additional commentary of1306your own if desired.13071308[[undoing-a-merge]]1309undoing a merge1310---------------13111312If you get stuck and decide to just give up and throw the whole mess1313away, you can always return to the pre-merge state with13141315-------------------------------------------------1316$ git reset --hard HEAD1317-------------------------------------------------13181319Or, if you've already commited the merge that you want to throw away,13201321-------------------------------------------------1322$ git reset --hard HEAD^1323-------------------------------------------------13241325However, this last command can be dangerous in some cases--never1326throw away a commit you have already committed if that commit may1327itself have been merged into another branch, as doing so may confuse1328further merges.13291330Fast-forward merges1331-------------------13321333There is one special case not mentioned above, which is treated1334differently. Normally, a merge results in a merge commit, with two1335parents, one pointing at each of the two lines of development that1336were merged.13371338However, if one of the two lines of development is completely1339contained within the other--so every commit present in the one is1340already contained in the other--then git just performs a1341<<fast-forwards,fast forward>>; the head of the current branch is1342moved forward to point at the head of the merged-in branch, without1343any new commits being created.13441345Fixing mistakes1346---------------13471348If you've messed up the working tree, but haven't yet committed your1349mistake, you can return the entire working tree to the last committed1350state with13511352-------------------------------------------------1353$ git reset --hard HEAD1354-------------------------------------------------13551356If you make a commit that you later wish you hadn't, there are two1357fundamentally different ways to fix the problem:13581359 1. You can create a new commit that undoes whatever was done1360 by the previous commit. This is the correct thing if your1361 mistake has already been made public.13621363 2. You can go back and modify the old commit. You should1364 never do this if you have already made the history public;1365 git does not normally expect the "history" of a project to1366 change, and cannot correctly perform repeated merges from1367 a branch that has had its history changed.13681369Fixing a mistake with a new commit1370~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~13711372Creating a new commit that reverts an earlier change is very easy;1373just pass the gitlink:git-revert[1] command a reference to the bad1374commit; for example, to revert the most recent commit:13751376-------------------------------------------------1377$ git revert HEAD1378-------------------------------------------------13791380This will create a new commit which undoes the change in HEAD. You1381will be given a chance to edit the commit message for the new commit.13821383You can also revert an earlier change, for example, the next-to-last:13841385-------------------------------------------------1386$ git revert HEAD^1387-------------------------------------------------13881389In this case git will attempt to undo the old change while leaving1390intact any changes made since then. If more recent changes overlap1391with the changes to be reverted, then you will be asked to fix1392conflicts manually, just as in the case of <<resolving-a-merge,1393resolving a merge>>.13941395Fixing a mistake by editing history1396~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~13971398If the problematic commit is the most recent commit, and you have not1399yet made that commit public, then you may just1400<<undoing-a-merge,destroy it using git-reset>>.14011402Alternatively, you1403can edit the working directory and update the index to fix your1404mistake, just as if you were going to <<how-to-make-a-commit,create a1405new commit>>, then run14061407-------------------------------------------------1408$ git commit --amend1409-------------------------------------------------14101411which will replace the old commit by a new commit incorporating your1412changes, giving you a chance to edit the old commit message first.14131414Again, you should never do this to a commit that may already have1415been merged into another branch; use gitlink:git-revert[1] instead in1416that case.14171418It is also possible to edit commits further back in the history, but1419this is an advanced topic to be left for1420<<cleaning-up-history,another chapter>>.14211422Checking out an old version of a file1423~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~14241425In the process of undoing a previous bad change, you may find it1426useful to check out an older version of a particular file using1427gitlink:git-checkout[1]. We've used git checkout before to switch1428branches, but it has quite different behavior if it is given a path1429name: the command14301431-------------------------------------------------1432$ git checkout HEAD^ path/to/file1433-------------------------------------------------14341435replaces path/to/file by the contents it had in the commit HEAD^, and1436also updates the index to match. It does not change branches.14371438If you just want to look at an old version of the file, without1439modifying the working directory, you can do that with1440gitlink:git-show[1]:14411442-------------------------------------------------1443$ git show HEAD^ path/to/file1444-------------------------------------------------14451446which will display the given version of the file.14471448Ensuring good performance1449-------------------------14501451On large repositories, git depends on compression to keep the history1452information from taking up to much space on disk or in memory.14531454This compression is not performed automatically. Therefore you1455should occasionally run14561457-------------------------------------------------1458$ git gc1459-------------------------------------------------14601461to recompress the archive and to prune any commits which are no1462longer referred to anywhere. This can be very time-consuming, and1463you should not modify the repository while it is working, so you1464should run it while you are not working.14651466Sharing development with others1467===============================14681469[[getting-updates-with-git-pull]]1470Getting updates with git pull1471-----------------------------14721473After you clone a repository and make a few changes of your own, you1474may wish to check the original repository for updates and merge them1475into your own work.14761477We have already seen <<Updating-a-repository-with-git-fetch,how to1478keep remote tracking branches up to date>> with gitlink:git-fetch[1],1479and how to merge two branches. So you can merge in changes from the1480original repository's master branch with:14811482-------------------------------------------------1483$ git fetch1484$ git merge origin/master1485-------------------------------------------------14861487However, the gitlink:git-pull[1] command provides a way to do this in1488one step:14891490-------------------------------------------------1491$ git pull origin master1492-------------------------------------------------14931494In fact, "origin" is normally the default repository to pull from,1495and the default branch is normally the HEAD of the remote repository,1496so often you can accomplish the above with just14971498-------------------------------------------------1499$ git pull1500-------------------------------------------------15011502See the descriptions of the branch.<name>.remote and1503branch.<name>.merge options in gitlink:git-repo-config[1] to learn1504how to control these defaults depending on the current branch.15051506In addition to saving you keystrokes, "git pull" also helps you by1507producing a default commit message documenting the branch and1508repository that you pulled from.15091510(But note that no such commit will be created in the case of a1511<<fast-forwards,fast forward>>; instead, your branch will just be1512updated to point to the latest commit from the upstream branch).15131514The git-pull command can also be given "." as the "remote" repository, in1515which case it just merges in a branch from the current repository; so1516the commands15171518-------------------------------------------------1519$ git pull . branch1520$ git merge branch1521-------------------------------------------------15221523are roughly equivalent. The former is actually very commonly used.15241525Submitting patches to a project1526-------------------------------15271528If you just have a few changes, the simplest way to submit them may1529just be to send them as patches in email:15301531First, use gitlink:git-format-patches[1]; for example:15321533-------------------------------------------------1534$ git format-patch origin1535-------------------------------------------------15361537will produce a numbered series of files in the current directory, one1538for each patch in the current branch but not in origin/HEAD.15391540You can then import these into your mail client and send them by1541hand. However, if you have a lot to send at once, you may prefer to1542use the gitlink:git-send-email[1] script to automate the process.1543Consult the mailing list for your project first to determine how they1544prefer such patches be handled.15451546Importing patches to a project1547------------------------------15481549Git also provides a tool called gitlink:git-am[1] (am stands for1550"apply mailbox"), for importing such an emailed series of patches.1551Just save all of the patch-containing messages, in order, into a1552single mailbox file, say "patches.mbox", then run15531554-------------------------------------------------1555$ git am -3 patches.mbox1556-------------------------------------------------15571558Git will apply each patch in order; if any conflicts are found, it1559will stop, and you can fix the conflicts as described in1560"<<resolving-a-merge,Resolving a merge>>". (The "-3" option tells1561git to perform a merge; if you would prefer it just to abort and1562leave your tree and index untouched, you may omit that option.)15631564Once the index is updated with the results of the conflict1565resolution, instead of creating a new commit, just run15661567-------------------------------------------------1568$ git am --resolved1569-------------------------------------------------15701571and git will create the commit for you and continue applying the1572remaining patches from the mailbox.15731574The final result will be a series of commits, one for each patch in1575the original mailbox, with authorship and commit log message each1576taken from the message containing each patch.15771578[[setting-up-a-public-repository]]1579Setting up a public repository1580------------------------------15811582Another way to submit changes to a project is to simply tell the1583maintainer of that project to pull from your repository, exactly as1584you did in the section "<<getting-updates-with-git-pull, Getting1585updates with git pull>>".15861587If you and maintainer both have accounts on the same machine, then1588then you can just pull changes from each other's repositories1589directly; note that all of the command (gitlink:git-clone[1],1590git-fetch[1], git-pull[1], etc.) which accept a URL as an argument1591will also accept a local file patch; so, for example, you can1592use15931594-------------------------------------------------1595$ git clone /path/to/repository1596$ git pull /path/to/other/repository1597-------------------------------------------------15981599If this sort of setup is inconvenient or impossible, another (more1600common) option is to set up a public repository on a public server.1601This also allows you to cleanly separate private work in progress1602from publicly visible work.16031604You will continue to do your day-to-day work in your personal1605repository, but periodically "push" changes from your personal1606repository into your public repository, allowing other developers to1607pull from that repository. So the flow of changes, in a situation1608where there is one other developer with a public repository, looks1609like this:16101611 you push1612 your personal repo ------------------> your public repo1613 ^ |1614 | |1615 | you pull | they pull1616 | |1617 | |1618 | they push V1619 their public repo <------------------- their repo16201621Now, assume your personal repository is in the directory ~/proj. We1622first create a new clone of the repository:16231624-------------------------------------------------1625$ git clone --bare proj-clone.git1626-------------------------------------------------16271628The resulting directory proj-clone.git will contains a "bare" git1629repository--it is just the contents of the ".git" directory, without1630a checked-out copy of a working directory.16311632Next, copy proj-clone.git to the server where you plan to host the1633public repository. You can use scp, rsync, or whatever is most1634convenient.16351636If somebody else maintains the public server, they may already have1637set up a git service for you, and you may skip to the section1638"<<pushing-changes-to-a-public-repository,Pushing changes to a public1639repository>>", below.16401641Otherwise, the following sections explain how to export your newly1642created public repository:16431644[[exporting-via-http]]1645Exporting a git repository via http1646-----------------------------------16471648The git protocol gives better performance and reliability, but on a1649host with a web server set up, http exports may be simpler to set up.16501651All you need to do is place the newly created bare git repository in1652a directory that is exported by the web server, and make some1653adjustments to give web clients some extra information they need:16541655-------------------------------------------------1656$ mv proj.git /home/you/public_html/proj.git1657$ cd proj.git1658$ git update-server-info1659$ chmod a+x hooks/post-update1660-------------------------------------------------16611662(For an explanation of the last two lines, see1663gitlink:git-update-server-info[1], and the documentation1664link:hooks.txt[Hooks used by git].)16651666Advertise the url of proj.git. Anybody else should then be able to1667clone or pull from that url, for example with a commandline like:16681669-------------------------------------------------1670$ git clone http://yourserver.com/~you/proj.git1671-------------------------------------------------16721673(See also1674link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]1675for a slightly more sophisticated setup using WebDAV which also1676allows pushing over http.)16771678[[exporting-via-git]]1679Exporting a git repository via the git protocol1680-----------------------------------------------16811682This is the preferred method.16831684For now, we refer you to the gitlink:git-daemon[1] man page for1685instructions. (See especially the examples section.)16861687[[pushing-changes-to-a-public-repository]]1688Pushing changes to a public repository1689--------------------------------------16901691Note that the two techniques outline above (exporting via1692<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other1693maintainers to fetch your latest changes, but they do not allow write1694access, which you will need to update the public repository with the1695latest changes created in your private repository.16961697The simplest way to do this is using gitlink:git-push[1] and ssh; to1698update the remote branch named "master" with the latest state of your1699branch named "master", run17001701-------------------------------------------------1702$ git push ssh://yourserver.com/~you/proj.git master:master1703-------------------------------------------------17041705or just17061707-------------------------------------------------1708$ git push ssh://yourserver.com/~you/proj.git master1709-------------------------------------------------17101711As with git-fetch, git-push will complain if this does not result in1712a <<fast-forwards,fast forward>>. Normally this is a sign of1713something wrong. However, if you are sure you know what you're1714doing, you may force git-push to perform the update anyway by1715proceeding the branch name by a plus sign:17161717-------------------------------------------------1718$ git push ssh://yourserver.com/~you/proj.git +master1719-------------------------------------------------17201721As with git-fetch, you may also set up configuration options to1722save typing; so, for example, after17231724-------------------------------------------------1725$ cat >.git/config <<EOF1726[remote "public-repo"]1727 url = ssh://yourserver.com/~you/proj.git1728EOF1729-------------------------------------------------17301731you should be able to perform the above push with just17321733-------------------------------------------------1734$ git push public-repo master1735-------------------------------------------------17361737See the explanations of the remote.<name>.url, branch.<name>.remote,1738and remote.<name>.push options in gitlink:git-repo-config[1] for1739details.17401741Setting up a shared repository1742------------------------------17431744Another way to collaborate is by using a model similar to that1745commonly used in CVS, where several developers with special rights1746all push to and pull from a single shared repository. See1747link:cvs-migration.txt[git for CVS users] for instructions on how to1748set this up.17491750Allow web browsing of a repository1751----------------------------------17521753TODO: Brief setup-instructions for gitweb17541755Examples1756--------17571758TODO: topic branches, typical roles as in everyday.txt, ?175917601761Working with other version control systems1762==========================================17631764TODO: CVS, Subversion, series-of-release-tarballs, ?17651766[[cleaning-up-history]]1767Rewriting history and maintaining patch series1768==============================================17691770Normally commits are only added to a project, never taken away or1771replaced. Git is designed with this assumption, and violating it will1772cause git's merge machinery (for example) to do the wrong thing.17731774However, there is a situation in which it can be useful to violate this1775assumption.17761777Creating the perfect patch series1778---------------------------------17791780Suppose you are a contributor to a large project, and you want to add a1781complicated feature, and to present it to the other developers in a way1782that makes it easy for them to read your changes, verify that they are1783correct, and understand why you made each change.17841785If you present all of your changes as a single patch (or commit), they may1786find it is too much to digest all at once.17871788If you present them with the entire history of your work, complete with1789mistakes, corrections, and dead ends, they may be overwhelmed.17901791So the ideal is usually to produce a series of patches such that:17921793 1. Each patch can be applied in order.17941795 2. Each patch includes a single logical change, together with a1796 message explaining the change.17971798 3. No patch introduces a regression: after applying any initial1799 part of the series, the resulting project still compiles and1800 works, and has no bugs that it didn't have before.18011802 4. The complete series produces the same end result as your own1803 (probably much messier!) development process did.18041805We will introduce some tools that can help you do this, explain how to use1806them, and then explain some of the problems that can arise because you are1807rewriting history.18081809Keeping a patch series up to date using git-rebase1810--------------------------------------------------18111812Suppose you have a series of commits in a branch "mywork", which1813originally branched off from "origin".18141815Suppose you create a branch "mywork" on a remote-tracking branch "origin",1816and created some commits on top of it:18171818-------------------------------------------------1819$ git checkout -b mywork origin1820$ vi file.txt1821$ git commit1822$ vi otherfile.txt1823$ git commit1824...1825-------------------------------------------------18261827You have performed no merges into mywork, so it is just a simple linear1828sequence of patches on top of "origin":182918301831 o--o--o <-- origin1832 \1833 o--o--o <-- mywork18341835Some more interesting work has been done in the upstream project, and1836"origin" has advanced:18371838 o--o--O--o--o--o <-- origin1839 \1840 a--b--c <-- mywork18411842At this point, you could use "pull" to merge your changes back in;1843the result would create a new merge commit, like this:184418451846 o--o--O--o--o--o <-- origin1847 \ \1848 a--b--c--m <-- mywork18491850However, if you prefer to keep the history in mywork a simple series of1851commits without any merges, you may instead choose to use1852gitlink:git-rebase[1]:18531854-------------------------------------------------1855$ git checkout mywork1856$ git rebase origin1857-------------------------------------------------18581859This will remove each of your commits from mywork, temporarily saving them1860as patches (in a directory named ".dotest"), update mywork to point at the1861latest version of origin, then apply each of the saved patches to the new1862mywork. The result will look like:186318641865 o--o--O--o--o--o <-- origin1866 \1867 a'--b'--c' <-- mywork18681869In the process, it may discover conflicts. In that case it will stop and1870allow you to fix the conflicts as described in1871"<<resolving-a-merge,Resolving a merge>>".18721873XXX: no, maybe not: git diff doesn't produce very useful results, and there's1874no MERGE_HEAD.18751876Once the index is updated with1877the results of the conflict resolution, instead of creating a new commit,1878just run18791880-------------------------------------------------1881$ git rebase --continue1882-------------------------------------------------18831884and git will continue applying the rest of the patches.18851886At any point you may use the --abort option to abort this process and1887return mywork to the state it had before you started the rebase:18881889-------------------------------------------------1890$ git rebase --abort1891-------------------------------------------------18921893Reordering or selecting from a patch series1894-------------------------------------------18951896Given one existing commit, the gitlink:git-cherry-pick[1] command allows1897you to apply the change introduced by that commit and create a new commit1898that records it.18991900This can be useful for modifying a patch series.19011902TODO: elaborate19031904Other tools1905-----------19061907There are numerous other tools, such as stgit, which exist for the purpose1908of maintianing a patch series. These are out of the scope of this manual.19091910Problems with rewriting history1911-------------------------------19121913The primary problem with rewriting the history of a branch has to do with1914merging.19151916TODO: elaborate191719181919Git internals1920=============19211922Architectural overview1923----------------------19241925TODO: Sources, README, core-tutorial, tutorial-2.txt, technical/19261927Glossary of git terms1928=====================19291930include::glossary.txt[]19311932Notes and todo list for this manual1933===================================19341935This is a work in progress.19361937The basic requirements:1938 - It must be readable in order, from beginning to end, by1939 someone intelligent with a basic grasp of the unix1940 commandline, but without any special knowledge of git. If1941 necessary, any other prerequisites should be specifically1942 mentioned as they arise.1943 - Whenever possible, section headings should clearly describe1944 the task they explain how to do, in language that requires1945 no more knowledge than necessary: for example, "importing1946 patches into a project" rather than "the git-am command"19471948Think about how to create a clear chapter dependency graph that will1949allow people to get to important topics without necessarily reading1950everything in between.19511952Scan Documentation/ for other stuff left out; in particular:1953 howto's1954 README1955 some of technical/?1956 hooks1957 etc.19581959Scan email archives for other stuff left out19601961Scan man pages to see if any assume more background than this manual1962provides.19631964Simplify beginning by suggesting disconnected head instead of1965temporary branch creation.19661967Explain how to refer to file stages in the "how to resolve a merge"1968section: diff -1, -2, -3, --ours, --theirs :1:/path notation. The1969"git ls-files --unmerged --stage" thing is sorta useful too,1970actually. And note gitk --merge. Also what's easiest way to see1971common merge base? Note also text where I claim rebase and am1972conflicts are resolved like merges isn't generally true, at least by1973default--fix.19741975Add more good examples. Entire sections of just cookbook examples1976might be a good idea; maybe make an "advanced examples" section a1977standard end-of-chapter section?19781979Include cross-references to the glossary, where appropriate.19801981Add quickstart as first chapter.19821983To document:1984 reflogs, git reflog expire1985 shallow clones?? See draft 1.5.0 release notes for some documentation.