3f231811523f41cd67d11f7de884e5d572e10f9e
   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 origin
1001e05db0fd4f31dde7005f075a84f96b360d05984b
1002$ git rev-list master
1003e05db0fd4f31dde7005f075a84f96b360d05984b
1004-------------------------------------------------
1005
1006Or you could recall that the ... operator selects all commits
1007contained reachable from either one reference or the other but not
1008both: so
1009
1010-------------------------------------------------
1011$ git log origin...master
1012-------------------------------------------------
1013
1014will return no commits when the two branches are equal.
1015
1016Check which tagged version a given fix was first included in
1017~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1018
1019Suppose you know that the commit e05db0fd fixed a certain problem.
1020You'd like to find the earliest tagged release that contains that
1021fix.
1022
1023Of course, there may be more than one answer--if the history branched
1024after commit e05db0fd, then there could be multiple "earliest" tagged
1025releases.
1026
1027You could just visually inspect the commits since e05db0fd:
1028
1029-------------------------------------------------
1030$ gitk e05db0fd..
1031-------------------------------------------------
1032
1033...
1034
1035Developing with git
1036===================
1037
1038Telling git your name
1039---------------------
1040
1041Before creating any commits, you should introduce yourself to git.  The
1042easiest way to do so is:
1043
1044------------------------------------------------
1045$ cat >~/.gitconfig <<\EOF
1046[user]
1047        name = Your Name Comes Here
1048        email = you@yourdomain.example.com
1049EOF
1050------------------------------------------------
1051
1052
1053Creating a new repository
1054-------------------------
1055
1056Creating a new repository from scratch is very easy:
1057
1058-------------------------------------------------
1059$ mkdir project
1060$ cd project
1061$ git init
1062-------------------------------------------------
1063
1064If you have some initial content (say, a tarball):
1065
1066-------------------------------------------------
1067$ tar -xzvf project.tar.gz
1068$ cd project
1069$ git init
1070$ git add . # include everything below ./ in the first commit:
1071$ git commit
1072-------------------------------------------------
1073
1074[[how-to-make-a-commit]]
1075how to make a commit
1076--------------------
1077
1078Creating a new commit takes three steps:
1079
1080        1. Making some changes to the working directory using your
1081           favorite editor.
1082        2. Telling git about your changes.
1083        3. Creating the commit using the content you told git about
1084           in step 2.
1085
1086In practice, you can interleave and repeat steps 1 and 2 as many
1087times as you want: in order to keep track of what you want committed
1088at step 3, git maintains a snapshot of the tree's contents in a
1089special staging area called "the index."
1090
1091At the beginning, the content of the index will be identical to
1092that of the HEAD.  The command "git diff --cached", which shows
1093the difference between the HEAD and the index, should therefore
1094produce no output at that point.
1095
1096Modifying the index is easy:
1097
1098To update the index with the new contents of a modified file, use
1099
1100-------------------------------------------------
1101$ git add path/to/file
1102-------------------------------------------------
1103
1104To add the contents of a new file to the index, use
1105
1106-------------------------------------------------
1107$ git add path/to/file
1108-------------------------------------------------
1109
1110To remove a file from the index and from the working tree,
1111
1112-------------------------------------------------
1113$ git rm path/to/file
1114-------------------------------------------------
1115
1116After each step you can verify that
1117
1118-------------------------------------------------
1119$ git diff --cached
1120-------------------------------------------------
1121
1122always shows the difference between the HEAD and the index file--this
1123is what you'd commit if you created the commit now--and that
1124
1125-------------------------------------------------
1126$ git diff
1127-------------------------------------------------
1128
1129shows the difference between the working tree and the index file.
1130
1131Note that "git add" always adds just the current contents of a file
1132to the index; further changes to the same file will be ignored unless
1133you run git-add on the file again.
1134
1135When you're ready, just run
1136
1137-------------------------------------------------
1138$ git commit
1139-------------------------------------------------
1140
1141and git will prompt you for a commit message and then create the new
1142commmit.  Check to make sure it looks like what you expected with
1143
1144-------------------------------------------------
1145$ git show
1146-------------------------------------------------
1147
1148As a special shortcut,
1149                
1150-------------------------------------------------
1151$ git commit -a
1152-------------------------------------------------
1153
1154will update the index with any files that you've modified or removed
1155and create a commit, all in one step.
1156
1157A number of commands are useful for keeping track of what you're
1158about to commit:
1159
1160-------------------------------------------------
1161$ git diff --cached # difference between HEAD and the index; what
1162                    # would be commited if you ran "commit" now.
1163$ git diff          # difference between the index file and your
1164                    # working directory; changes that would not
1165                    # be included if you ran "commit" now.
1166$ git status        # a brief per-file summary of the above.
1167-------------------------------------------------
1168
1169creating good commit messages
1170-----------------------------
1171
1172Though not required, it's a good idea to begin the commit message
1173with a single short (less than 50 character) line summarizing the
1174change, followed by a blank line and then a more thorough
1175description.  Tools that turn commits into email, for example, use
1176the first line on the Subject line and the rest of the commit in the
1177body.
1178
1179how to merge
1180------------
1181
1182You can rejoin two diverging branches of development using
1183gitlink:git-merge[1]:
1184
1185-------------------------------------------------
1186$ git merge branchname
1187-------------------------------------------------
1188
1189merges the development in the branch "branchname" into the current
1190branch.  If there are conflicts--for example, if the same file is
1191modified in two different ways in the remote branch and the local
1192branch--then you are warned; the output may look something like this:
1193
1194-------------------------------------------------
1195$ git pull . next
1196Trying really trivial in-index merge...
1197fatal: Merge requires file-level merging
1198Nope.
1199Merging HEAD with 77976da35a11db4580b80ae27e8d65caf5208086
1200Merging:
120115e2162 world
120277976da goodbye
1203found 1 common ancestor(s):
1204d122ed4 initial
1205Auto-merging file.txt
1206CONFLICT (content): Merge conflict in file.txt
1207Automatic merge failed; fix conflicts and then commit the result.
1208-------------------------------------------------
1209
1210Conflict markers are left in the problematic files, and after
1211you resolve the conflicts manually, you can update the index
1212with the contents and run git commit, as you normally would when
1213creating a new file.
1214
1215If you examine the resulting commit using gitk, you will see that it
1216has two parents, one pointing to the top of the current branch, and
1217one to the top of the other branch.
1218
1219In more detail:
1220
1221[[resolving-a-merge]]
1222Resolving a merge
1223-----------------
1224
1225When a merge isn't resolved automatically, git leaves the index and
1226the working tree in a special state that gives you all the
1227information you need to help resolve the merge.
1228
1229Files with conflicts are marked specially in the index, so until you
1230resolve the problem and update the index, git commit will fail:
1231
1232-------------------------------------------------
1233$ git commit
1234file.txt: needs merge
1235-------------------------------------------------
1236
1237Also, git status will list those files as "unmerged".
1238
1239All of the changes that git was able to merge automatically are
1240already added to the index file, so gitlink:git-diff[1] shows only
1241the conflicts.  Also, it uses a somewhat unusual syntax:
1242
1243-------------------------------------------------
1244$ git diff
1245diff --cc file.txt
1246index 802992c,2b60207..0000000
1247--- a/file.txt
1248+++ b/file.txt
1249@@@ -1,1 -1,1 +1,5 @@@
1250++<<<<<<< HEAD:file.txt
1251 +Hello world
1252++=======
1253+ Goodbye
1254++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1255-------------------------------------------------
1256
1257Recall that the commit which will be commited after we resolve this
1258conflict will have two parents instead of the usual one: one parent
1259will be HEAD, the tip of the current branch; the other will be the
1260tip of the other branch, which is stored temporarily in MERGE_HEAD.
1261
1262The diff above shows the differences between the working-tree version
1263of file.txt and two previous version: one version from HEAD, and one
1264from MERGE_HEAD.  So instead of preceding each line by a single "+"
1265or "-", it now uses two columns: the first column is used for
1266differences between the first parent and the working directory copy,
1267and the second for differences between the second parent and the
1268working directory copy.  Thus after resolving the conflict in the
1269obvious way, the diff will look like:
1270
1271-------------------------------------------------
1272$ git diff
1273diff --cc file.txt
1274index 802992c,2b60207..0000000
1275--- a/file.txt
1276+++ b/file.txt
1277@@@ -1,1 -1,1 +1,1 @@@
1278- Hello world
1279 -Goodbye
1280++Goodbye world
1281-------------------------------------------------
1282
1283This shows that our resolved version deleted "Hello world" from the
1284first parent, deleted "Goodbye" from the second parent, and added
1285"Goodbye world", which was previously absent from both.
1286
1287The gitlink:git-log[1] command also provides special help for merges:
1288
1289-------------------------------------------------
1290$ git log --merge
1291-------------------------------------------------
1292
1293This will list all commits which exist only on HEAD or on MERGE_HEAD,
1294and which touch an unmerged file.
1295
1296We can now add the resolved version to the index and commit:
1297
1298-------------------------------------------------
1299$ git add file.txt
1300$ git commit
1301-------------------------------------------------
1302
1303Note that the commit message will already be filled in for you with
1304some information about the merge.  Normally you can just use this
1305default message unchanged, but you may add additional commentary of
1306your own if desired.
1307
1308[[undoing-a-merge]]
1309undoing a merge
1310---------------
1311
1312If you get stuck and decide to just give up and throw the whole mess
1313away, you can always return to the pre-merge state with
1314
1315-------------------------------------------------
1316$ git reset --hard HEAD
1317-------------------------------------------------
1318
1319Or, if you've already commited the merge that you want to throw away,
1320
1321-------------------------------------------------
1322$ git reset --hard HEAD^
1323-------------------------------------------------
1324
1325However, this last command can be dangerous in some cases--never
1326throw away a commit you have already committed if that commit may
1327itself have been merged into another branch, as doing so may confuse
1328further merges.
1329
1330Fast-forward merges
1331-------------------
1332
1333There is one special case not mentioned above, which is treated
1334differently.  Normally, a merge results in a merge commit, with two
1335parents, one pointing at each of the two lines of development that
1336were merged.
1337
1338However, if one of the two lines of development is completely
1339contained within the other--so every commit present in the one is
1340already contained in the other--then git just performs a
1341<<fast-forwards,fast forward>>; the head of the current branch is
1342moved forward to point at the head of the merged-in branch, without
1343any new commits being created.
1344
1345Fixing mistakes
1346---------------
1347
1348If you've messed up the working tree, but haven't yet committed your
1349mistake, you can return the entire working tree to the last committed
1350state with
1351
1352-------------------------------------------------
1353$ git reset --hard HEAD
1354-------------------------------------------------
1355
1356If you make a commit that you later wish you hadn't, there are two
1357fundamentally different ways to fix the problem:
1358
1359        1. You can create a new commit that undoes whatever was done
1360        by the previous commit.  This is the correct thing if your
1361        mistake has already been made public.
1362
1363        2. You can go back and modify the old commit.  You should
1364        never do this if you have already made the history public;
1365        git does not normally expect the "history" of a project to
1366        change, and cannot correctly perform repeated merges from
1367        a branch that has had its history changed.
1368
1369Fixing a mistake with a new commit
1370~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1371
1372Creating a new commit that reverts an earlier change is very easy;
1373just pass the gitlink:git-revert[1] command a reference to the bad
1374commit; for example, to revert the most recent commit:
1375
1376-------------------------------------------------
1377$ git revert HEAD
1378-------------------------------------------------
1379
1380This will create a new commit which undoes the change in HEAD.  You
1381will be given a chance to edit the commit message for the new commit.
1382
1383You can also revert an earlier change, for example, the next-to-last:
1384
1385-------------------------------------------------
1386$ git revert HEAD^
1387-------------------------------------------------
1388
1389In this case git will attempt to undo the old change while leaving
1390intact any changes made since then.  If more recent changes overlap
1391with the changes to be reverted, then you will be asked to fix
1392conflicts manually, just as in the case of <<resolving-a-merge,
1393resolving a merge>>.
1394
1395Fixing a mistake by editing history
1396~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1397
1398If the problematic commit is the most recent commit, and you have not
1399yet made that commit public, then you may just
1400<<undoing-a-merge,destroy it using git-reset>>.
1401
1402Alternatively, you
1403can edit the working directory and update the index to fix your
1404mistake, just as if you were going to <<how-to-make-a-commit,create a
1405new commit>>, then run
1406
1407-------------------------------------------------
1408$ git commit --amend
1409-------------------------------------------------
1410
1411which will replace the old commit by a new commit incorporating your
1412changes, giving you a chance to edit the old commit message first.
1413
1414Again, you should never do this to a commit that may already have
1415been merged into another branch; use gitlink:git-revert[1] instead in
1416that case.
1417
1418It is also possible to edit commits further back in the history, but
1419this is an advanced topic to be left for
1420<<cleaning-up-history,another chapter>>.
1421
1422Checking out an old version of a file
1423~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1424
1425In the process of undoing a previous bad change, you may find it
1426useful to check out an older version of a particular file using
1427gitlink:git-checkout[1].  We've used git checkout before to switch
1428branches, but it has quite different behavior if it is given a path
1429name: the command
1430
1431-------------------------------------------------
1432$ git checkout HEAD^ path/to/file
1433-------------------------------------------------
1434
1435replaces path/to/file by the contents it had in the commit HEAD^, and
1436also updates the index to match.  It does not change branches.
1437
1438If you just want to look at an old version of the file, without
1439modifying the working directory, you can do that with
1440gitlink:git-show[1]:
1441
1442-------------------------------------------------
1443$ git show HEAD^ path/to/file
1444-------------------------------------------------
1445
1446which will display the given version of the file.
1447
1448Ensuring good performance
1449-------------------------
1450
1451On large repositories, git depends on compression to keep the history
1452information from taking up to much space on disk or in memory.
1453
1454This compression is not performed automatically.  Therefore you
1455should occasionally run
1456
1457-------------------------------------------------
1458$ git gc
1459-------------------------------------------------
1460
1461to recompress the archive and to prune any commits which are no
1462longer referred to anywhere.  This can be very time-consuming, and
1463you should not modify the repository while it is working, so you
1464should run it while you are not working.
1465
1466Sharing development with others
1467===============================
1468
1469[[getting-updates-with-git-pull]]
1470Getting updates with git pull
1471-----------------------------
1472
1473After you clone a repository and make a few changes of your own, you
1474may wish to check the original repository for updates and merge them
1475into your own work.
1476
1477We have already seen <<Updating-a-repository-with-git-fetch,how to
1478keep remote tracking branches up to date>> with gitlink:git-fetch[1],
1479and how to merge two branches.  So you can merge in changes from the
1480original repository's master branch with:
1481
1482-------------------------------------------------
1483$ git fetch
1484$ git merge origin/master
1485-------------------------------------------------
1486
1487However, the gitlink:git-pull[1] command provides a way to do this in
1488one step:
1489
1490-------------------------------------------------
1491$ git pull origin master
1492-------------------------------------------------
1493
1494In 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 just
1497
1498-------------------------------------------------
1499$ git pull
1500-------------------------------------------------
1501
1502See the descriptions of the branch.<name>.remote and
1503branch.<name>.merge options in gitlink:git-repo-config[1] to learn
1504how to control these defaults depending on the current branch.
1505
1506In addition to saving you keystrokes, "git pull" also helps you by
1507producing a default commit message documenting the branch and
1508repository that you pulled from.
1509
1510(But note that no such commit will be created in the case of a
1511<<fast-forwards,fast forward>>; instead, your branch will just be
1512updated to point to the latest commit from the upstream branch).
1513
1514The git-pull command can also be given "." as the "remote" repository, in
1515which case it just merges in a branch from the current repository; so
1516the commands
1517
1518-------------------------------------------------
1519$ git pull . branch
1520$ git merge branch
1521-------------------------------------------------
1522
1523are roughly equivalent.  The former is actually very commonly used.
1524
1525Submitting patches to a project
1526-------------------------------
1527
1528If you just have a few changes, the simplest way to submit them may
1529just be to send them as patches in email:
1530
1531First, use gitlink:git-format-patches[1]; for example:
1532
1533-------------------------------------------------
1534$ git format-patch origin
1535-------------------------------------------------
1536
1537will produce a numbered series of files in the current directory, one
1538for each patch in the current branch but not in origin/HEAD.
1539
1540You can then import these into your mail client and send them by
1541hand.  However, if you have a lot to send at once, you may prefer to
1542use the gitlink:git-send-email[1] script to automate the process.
1543Consult the mailing list for your project first to determine how they
1544prefer such patches be handled.
1545
1546Importing patches to a project
1547------------------------------
1548
1549Git also provides a tool called gitlink:git-am[1] (am stands for
1550"apply mailbox"), for importing such an emailed series of patches.
1551Just save all of the patch-containing messages, in order, into a
1552single mailbox file, say "patches.mbox", then run
1553
1554-------------------------------------------------
1555$ git am -3 patches.mbox
1556-------------------------------------------------
1557
1558Git will apply each patch in order; if any conflicts are found, it
1559will stop, and you can fix the conflicts as described in
1560"<<resolving-a-merge,Resolving a merge>>".  (The "-3" option tells
1561git to perform a merge; if you would prefer it just to abort and
1562leave your tree and index untouched, you may omit that option.)
1563
1564Once the index is updated with the results of the conflict
1565resolution, instead of creating a new commit, just run
1566
1567-------------------------------------------------
1568$ git am --resolved
1569-------------------------------------------------
1570
1571and git will create the commit for you and continue applying the
1572remaining patches from the mailbox.
1573
1574The final result will be a series of commits, one for each patch in
1575the original mailbox, with authorship and commit log message each
1576taken from the message containing each patch.
1577
1578[[setting-up-a-public-repository]]
1579Setting up a public repository
1580------------------------------
1581
1582Another way to submit changes to a project is to simply tell the
1583maintainer of that project to pull from your repository, exactly as
1584you did in the section "<<getting-updates-with-git-pull, Getting
1585updates with git pull>>".
1586
1587If you and maintainer both have accounts on the same machine, then
1588then you can just pull changes from each other's repositories
1589directly; note that all of the command (gitlink:git-clone[1],
1590git-fetch[1], git-pull[1], etc.) which accept a URL as an argument
1591will also accept a local file patch; so, for example, you can
1592use
1593
1594-------------------------------------------------
1595$ git clone /path/to/repository
1596$ git pull /path/to/other/repository
1597-------------------------------------------------
1598
1599If this sort of setup is inconvenient or impossible, another (more
1600common) option is to set up a public repository on a public server.
1601This also allows you to cleanly separate private work in progress
1602from publicly visible work.
1603
1604You will continue to do your day-to-day work in your personal
1605repository, but periodically "push" changes from your personal
1606repository into your public repository, allowing other developers to
1607pull from that repository.  So the flow of changes, in a situation
1608where there is one other developer with a public repository, looks
1609like this:
1610
1611                        you push
1612  your personal repo ------------------> your public repo
1613        ^                                     |
1614        |                                     |
1615        | you pull                            | they pull
1616        |                                     |
1617        |                                     |
1618        |               they push             V
1619  their public repo <------------------- their repo
1620
1621Now, assume your personal repository is in the directory ~/proj.  We
1622first create a new clone of the repository:
1623
1624-------------------------------------------------
1625$ git clone --bare proj-clone.git
1626-------------------------------------------------
1627
1628The resulting directory proj-clone.git will contains a "bare" git
1629repository--it is just the contents of the ".git" directory, without
1630a checked-out copy of a working directory.
1631
1632Next, copy proj-clone.git to the server where you plan to host the
1633public repository.  You can use scp, rsync, or whatever is most
1634convenient.
1635
1636If somebody else maintains the public server, they may already have
1637set up a git service for you, and you may skip to the section
1638"<<pushing-changes-to-a-public-repository,Pushing changes to a public
1639repository>>", below.
1640
1641Otherwise, the following sections explain how to export your newly
1642created public repository:
1643
1644[[exporting-via-http]]
1645Exporting a git repository via http
1646-----------------------------------
1647
1648The git protocol gives better performance and reliability, but on a
1649host with a web server set up, http exports may be simpler to set up.
1650
1651All you need to do is place the newly created bare git repository in
1652a directory that is exported by the web server, and make some
1653adjustments to give web clients some extra information they need:
1654
1655-------------------------------------------------
1656$ mv proj.git /home/you/public_html/proj.git
1657$ cd proj.git
1658$ git update-server-info
1659$ chmod a+x hooks/post-update
1660-------------------------------------------------
1661
1662(For an explanation of the last two lines, see
1663gitlink:git-update-server-info[1], and the documentation
1664link:hooks.txt[Hooks used by git].)
1665
1666Advertise the url of proj.git.  Anybody else should then be able to
1667clone or pull from that url, for example with a commandline like:
1668
1669-------------------------------------------------
1670$ git clone http://yourserver.com/~you/proj.git
1671-------------------------------------------------
1672
1673(See also
1674link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]
1675for a slightly more sophisticated setup using WebDAV which also
1676allows pushing over http.)
1677
1678[[exporting-via-git]]
1679Exporting a git repository via the git protocol
1680-----------------------------------------------
1681
1682This is the preferred method.
1683
1684For now, we refer you to the gitlink:git-daemon[1] man page for
1685instructions.  (See especially the examples section.)
1686
1687[[pushing-changes-to-a-public-repository]]
1688Pushing changes to a public repository
1689--------------------------------------
1690
1691Note that the two techniques outline above (exporting via
1692<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
1693maintainers to fetch your latest changes, but they do not allow write
1694access, which you will need to update the public repository with the
1695latest changes created in your private repository.
1696
1697The simplest way to do this is using gitlink:git-push[1] and ssh; to
1698update the remote branch named "master" with the latest state of your
1699branch named "master", run
1700
1701-------------------------------------------------
1702$ git push ssh://yourserver.com/~you/proj.git master:master
1703-------------------------------------------------
1704
1705or just
1706
1707-------------------------------------------------
1708$ git push ssh://yourserver.com/~you/proj.git master
1709-------------------------------------------------
1710
1711As with git-fetch, git-push will complain if this does not result in
1712a <<fast-forwards,fast forward>>.  Normally this is a sign of
1713something wrong.  However, if you are sure you know what you're
1714doing, you may force git-push to perform the update anyway by
1715proceeding the branch name by a plus sign:
1716
1717-------------------------------------------------
1718$ git push ssh://yourserver.com/~you/proj.git +master
1719-------------------------------------------------
1720
1721As with git-fetch, you may also set up configuration options to
1722save typing; so, for example, after
1723
1724-------------------------------------------------
1725$ cat >.git/config <<EOF
1726[remote "public-repo"]
1727        url = ssh://yourserver.com/~you/proj.git
1728EOF
1729-------------------------------------------------
1730
1731you should be able to perform the above push with just
1732
1733-------------------------------------------------
1734$ git push public-repo master
1735-------------------------------------------------
1736
1737See the explanations of the remote.<name>.url, branch.<name>.remote,
1738and remote.<name>.push options in gitlink:git-repo-config[1] for
1739details.
1740
1741Setting up a shared repository
1742------------------------------
1743
1744Another way to collaborate is by using a model similar to that
1745commonly used in CVS, where several developers with special rights
1746all push to and pull from a single shared repository.  See
1747link:cvs-migration.txt[git for CVS users] for instructions on how to
1748set this up.
1749
1750Allow web browsing of a repository
1751----------------------------------
1752
1753TODO: Brief setup-instructions for gitweb
1754
1755Examples
1756--------
1757
1758TODO: topic branches, typical roles as in everyday.txt, ?
1759
1760
1761Working with other version control systems
1762==========================================
1763
1764TODO: CVS, Subversion, series-of-release-tarballs, ?
1765
1766[[cleaning-up-history]]
1767Rewriting history and maintaining patch series
1768==============================================
1769
1770Normally commits are only added to a project, never taken away or
1771replaced.  Git is designed with this assumption, and violating it will
1772cause git's merge machinery (for example) to do the wrong thing.
1773
1774However, there is a situation in which it can be useful to violate this
1775assumption.
1776
1777Creating the perfect patch series
1778---------------------------------
1779
1780Suppose you are a contributor to a large project, and you want to add a
1781complicated feature, and to present it to the other developers in a way
1782that makes it easy for them to read your changes, verify that they are
1783correct, and understand why you made each change.
1784
1785If you present all of your changes as a single patch (or commit), they may
1786find it is too much to digest all at once.
1787
1788If you present them with the entire history of your work, complete with
1789mistakes, corrections, and dead ends, they may be overwhelmed.
1790
1791So the ideal is usually to produce a series of patches such that:
1792
1793        1. Each patch can be applied in order.
1794
1795        2. Each patch includes a single logical change, together with a
1796           message explaining the change.
1797
1798        3. No patch introduces a regression: after applying any initial
1799           part of the series, the resulting project still compiles and
1800           works, and has no bugs that it didn't have before.
1801
1802        4. The complete series produces the same end result as your own
1803           (probably much messier!) development process did.
1804
1805We will introduce some tools that can help you do this, explain how to use
1806them, and then explain some of the problems that can arise because you are
1807rewriting history.
1808
1809Keeping a patch series up to date using git-rebase
1810--------------------------------------------------
1811
1812Suppose you have a series of commits in a branch "mywork", which
1813originally branched off from "origin".
1814
1815Suppose you create a branch "mywork" on a remote-tracking branch "origin",
1816and created some commits on top of it:
1817
1818-------------------------------------------------
1819$ git checkout -b mywork origin
1820$ vi file.txt
1821$ git commit
1822$ vi otherfile.txt
1823$ git commit
1824...
1825-------------------------------------------------
1826
1827You have performed no merges into mywork, so it is just a simple linear
1828sequence of patches on top of "origin":
1829
1830
1831 o--o--o <-- origin
1832        \
1833         o--o--o <-- mywork
1834
1835Some more interesting work has been done in the upstream project, and
1836"origin" has advanced:
1837
1838 o--o--O--o--o--o <-- origin
1839        \
1840         a--b--c <-- mywork
1841
1842At this point, you could use "pull" to merge your changes back in;
1843the result would create a new merge commit, like this:
1844
1845
1846 o--o--O--o--o--o <-- origin
1847        \        \
1848         a--b--c--m <-- mywork
1849 
1850However, if you prefer to keep the history in mywork a simple series of
1851commits without any merges, you may instead choose to use
1852gitlink:git-rebase[1]:
1853
1854-------------------------------------------------
1855$ git checkout mywork
1856$ git rebase origin
1857-------------------------------------------------
1858
1859This will remove each of your commits from mywork, temporarily saving them
1860as patches (in a directory named ".dotest"), update mywork to point at the
1861latest version of origin, then apply each of the saved patches to the new
1862mywork.  The result will look like:
1863
1864
1865 o--o--O--o--o--o <-- origin
1866                 \
1867                  a'--b'--c' <-- mywork
1868
1869In the process, it may discover conflicts.  In that case it will stop and
1870allow you to fix the conflicts as described in
1871"<<resolving-a-merge,Resolving a merge>>".
1872
1873XXX: no, maybe not: git diff doesn't produce very useful results, and there's
1874no MERGE_HEAD.
1875
1876Once the index is updated with
1877the results of the conflict resolution, instead of creating a new commit,
1878just run
1879
1880-------------------------------------------------
1881$ git rebase --continue
1882-------------------------------------------------
1883
1884and git will continue applying the rest of the patches.
1885
1886At any point you may use the --abort option to abort this process and
1887return mywork to the state it had before you started the rebase:
1888
1889-------------------------------------------------
1890$ git rebase --abort
1891-------------------------------------------------
1892
1893Reordering or selecting from a patch series
1894-------------------------------------------
1895
1896Given one existing commit, the gitlink:git-cherry-pick[1] command allows
1897you to apply the change introduced by that commit and create a new commit
1898that records it.
1899
1900This can be useful for modifying a patch series.
1901
1902TODO: elaborate
1903
1904Other tools
1905-----------
1906
1907There are numerous other tools, such as stgit, which exist for the purpose
1908of maintianing a patch series.  These are out of the scope of this manual.
1909
1910Problems with rewriting history
1911-------------------------------
1912
1913The primary problem with rewriting the history of a branch has to do with
1914merging.
1915
1916TODO: elaborate
1917
1918
1919Git internals
1920=============
1921
1922Architectural overview
1923----------------------
1924
1925TODO: Sources, README, core-tutorial, tutorial-2.txt, technical/
1926
1927Glossary of git terms
1928=====================
1929
1930include::glossary.txt[]
1931
1932Notes and todo list for this manual
1933===================================
1934
1935This is a work in progress.
1936
1937The basic requirements:
1938        - It must be readable in order, from beginning to end, by
1939          someone intelligent with a basic grasp of the unix
1940          commandline, but without any special knowledge of git.  If
1941          necessary, any other prerequisites should be specifically
1942          mentioned as they arise.
1943        - Whenever possible, section headings should clearly describe
1944          the task they explain how to do, in language that requires
1945          no more knowledge than necessary: for example, "importing
1946          patches into a project" rather than "the git-am command"
1947
1948Think about how to create a clear chapter dependency graph that will
1949allow people to get to important topics without necessarily reading
1950everything in between.
1951
1952Scan Documentation/ for other stuff left out; in particular:
1953        howto's
1954        README
1955        some of technical/?
1956        hooks
1957        etc.
1958
1959Scan email archives for other stuff left out
1960
1961Scan man pages to see if any assume more background than this manual
1962provides.
1963
1964Simplify beginning by suggesting disconnected head instead of
1965temporary branch creation.
1966
1967Explain how to refer to file stages in the "how to resolve a merge"
1968section: diff -1, -2, -3, --ours, --theirs :1:/path notation.  The
1969"git ls-files --unmerged --stage" thing is sorta useful too,
1970actually.  And note gitk --merge.  Also what's easiest way to see
1971common merge base?  Note also text where I claim rebase and am
1972conflicts are resolved like merges isn't generally true, at least by
1973default--fix.
1974
1975Add more good examples.  Entire sections of just cookbook examples
1976might be a good idea; maybe make an "advanced examples" section a
1977standard end-of-chapter section?
1978
1979Include cross-references to the glossary, where appropriate.
1980
1981Add quickstart as first chapter.
1982
1983To document:
1984        reflogs, git reflog expire
1985        shallow clones??  See draft 1.5.0 release notes for some documentation.