267bbd736746dd338c0e429597a7ccbe2edb8dd7
   1Git User's Manual
   2_________________
   3
   4This manual is designed to be readable by someone with basic unix
   5commandline skills, but no previous knowledge of git.
   6
   7Chapter 1 gives a brief overview of git commands, without any
   8explanation; you can skip to chapter 2 on a first reading.
   9
  10Chapters 2 and 3 explain how to fetch and study a project using
  11git--the tools you'd need to build and test a particular version of a
  12software project, to search for regressions, and so on.
  13
  14Chapter 4 explains how to do development with git, and chapter 5 how
  15to share that development with others.
  16
  17Further chapters cover more specialized topics.
  18
  19Comprehensive reference documentation is available through the man
  20pages.  For a command such as "git clone", just use
  21
  22------------------------------------------------
  23$ man git-clone
  24------------------------------------------------
  25
  26Git Quick Start
  27===============
  28
  29This is a quick summary of the major commands; the following chapters
  30will explain how these work in more detail.
  31
  32Creating a new repository
  33-------------------------
  34
  35From a tarball:
  36
  37-----------------------------------------------
  38$ tar xzf project.tar.gz
  39$ cd project
  40$ git init
  41Initialized empty Git repository in .git/
  42$ git add .
  43$ git commit
  44-----------------------------------------------
  45
  46From a remote repository:
  47
  48-----------------------------------------------
  49$ git clone git://example.com/pub/project.git
  50$ cd project
  51-----------------------------------------------
  52
  53Managing branches
  54-----------------
  55
  56-----------------------------------------------
  57$ git branch         # list all branches in this repo
  58$ git checkout test  # switch working directory to branch "test"
  59$ git branch new     # create branch "new" starting at current HEAD
  60$ git branch -d new  # delete branch "new"
  61-----------------------------------------------
  62
  63Instead of basing new branch on current HEAD (the default), use:
  64
  65-----------------------------------------------
  66$ git branch new test    # branch named "test"
  67$ git branch new v2.6.15 # tag named v2.6.15
  68$ git branch new HEAD^   # commit before the most recent
  69$ git branch new HEAD^^  # commit before that
  70$ git branch new test~10 # ten commits before tip of branch "test"
  71-----------------------------------------------
  72
  73Create and switch to a new branch at the same time:
  74
  75-----------------------------------------------
  76$ git checkout -b new v2.6.15
  77-----------------------------------------------
  78
  79Update and examine branches from the repository you cloned from:
  80
  81-----------------------------------------------
  82$ git fetch             # update
  83$ git branch -r         # list
  84  origin/master
  85  origin/next
  86  ...
  87$ git branch checkout -b masterwork origin/master
  88-----------------------------------------------
  89
  90Fetch a branch from a different repository, and give it a new
  91name in your repository:
  92
  93-----------------------------------------------
  94$ git fetch git://example.com/project.git theirbranch:mybranch
  95$ git fetch git://example.com/project.git v2.6.15:mybranch
  96-----------------------------------------------
  97
  98Keep a list of repositories you work with regularly:
  99
 100-----------------------------------------------
 101$ git remote add example git://example.com/project.git
 102$ git remote            # list remote repositories
 103example
 104origin
 105$ git remote show example # get details
 106* remote example
 107  URL: git://example.com/project.git
 108  Tracked remote branches
 109    master next ...
 110$ git fetch example     # update branches from example
 111$ git branch -r         # list all remote branches
 112-----------------------------------------------
 113
 114
 115Exploring history
 116-----------------
 117
 118-----------------------------------------------
 119$ gitk                      # visualize and browse history
 120$ git log                   # list all commits
 121$ git log src/              # ...modifying src/
 122$ git log v2.6.15..v2.6.16  # ...in v2.6.16, not in v2.6.15
 123$ git log master..test      # ...in branch test, not in branch master
 124$ git log test..master      # ...in branch master, but not in test
 125$ git log test...master     # ...in one branch, not in both
 126$ git log -S'foo()'         # ...where difference contain "foo()"
 127$ git log --since="2 weeks ago"
 128$ git log -p                # show patches as well
 129$ git show                  # most recent commit
 130$ git diff v2.6.15..v2.6.16 # diff between two tagged versions
 131$ git diff v2.6.15..HEAD    # diff with current head
 132$ git grep "foo()"          # search working directory for "foo()"
 133$ git grep v2.6.15 "foo()"  # search old tree for "foo()"
 134$ git show v2.6.15:a.txt    # look at old version of a.txt
 135-----------------------------------------------
 136
 137Searching for regressions:
 138
 139-----------------------------------------------
 140$ git bisect start
 141$ git bisect bad                # current version is bad
 142$ git bisect good v2.6.13-rc2   # last known good revision
 143Bisecting: 675 revisions left to test after this
 144                                # test here, then:
 145$ git bisect good               # if this revision is good, or
 146$ git bisect bad                # if this revision is bad.
 147                                # repeat until done.
 148-----------------------------------------------
 149
 150Making changes
 151--------------
 152
 153Make sure git knows who to blame:
 154
 155------------------------------------------------
 156$ cat >~/.gitconfig <<\EOF
 157[user]
 158name = Your Name Comes Here
 159email = you@yourdomain.example.com
 160EOF
 161------------------------------------------------
 162
 163Select file contents to include in the next commit, then make the
 164commit:
 165
 166-----------------------------------------------
 167$ git add a.txt    # updated file
 168$ git add b.txt    # new file
 169$ git rm c.txt     # old file
 170$ git commit
 171-----------------------------------------------
 172
 173Or, prepare and create the commit in one step:
 174
 175-----------------------------------------------
 176$ git commit d.txt # use latest content of d.txt
 177$ git commit -a    # use latest content of all tracked files
 178-----------------------------------------------
 179
 180Merging
 181-------
 182
 183-----------------------------------------------
 184$ git merge test   # merge branch "test" into the current branch
 185$ git pull git://example.com/project.git master
 186                   # fetch and merge in remote branch
 187$ git pull . test  # equivalent to git merge test
 188-----------------------------------------------
 189
 190Sharing your changes
 191--------------------
 192
 193Importing or exporting patches:
 194
 195-----------------------------------------------
 196$ git format-patch origin..HEAD # format a patch for each commit
 197                                # in HEAD but not in origin
 198$ git-am mbox # import patches from the mailbox "mbox"
 199-----------------------------------------------
 200
 201Fetch a branch in a different git repository, then merge into the
 202current branch:
 203
 204-----------------------------------------------
 205$ git pull git://example.com/project.git theirbranch
 206-----------------------------------------------
 207
 208Store the fetched branch into a local branch before merging into the
 209current branch:
 210
 211-----------------------------------------------
 212$ git pull git://example.com/project.git theirbranch:mybranch
 213-----------------------------------------------
 214
 215After creating commits on a local branch, update the remote
 216branch with your commits:
 217
 218-----------------------------------------------
 219$ git push ssh://example.com/project.git mybranch:theirbranch
 220-----------------------------------------------
 221
 222When remote and local branch are both named "test":
 223
 224-----------------------------------------------
 225$ git push ssh://example.com/project.git test
 226-----------------------------------------------
 227
 228Shortcut version for a frequently used remote repository:
 229
 230-----------------------------------------------
 231$ git remote add example ssh://example.com/project.git
 232$ git push example test
 233-----------------------------------------------
 234
 235Repositories and Branches
 236=========================
 237
 238How to get a git repository
 239---------------------------
 240
 241It will be useful to have a git repository to experiment with as you
 242read this manual.
 243
 244The best way to get one is by using the gitlink:git-clone[1] command
 245to download a copy of an existing repository for a project that you
 246are interested in.  If you don't already have a project in mind, here
 247are some interesting examples:
 248
 249------------------------------------------------
 250        # git itself (approx. 10MB download):
 251$ git clone git://git.kernel.org/pub/scm/git/git.git
 252        # the linux kernel (approx. 150MB download):
 253$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
 254------------------------------------------------
 255
 256The initial clone may be time-consuming for a large project, but you
 257will only need to clone once.
 258
 259The clone command creates a new directory named after the project
 260("git" or "linux-2.6" in the examples above).  After you cd into this
 261directory, you will see that it contains a copy of the project files,
 262together with a special top-level directory named ".git", which
 263contains all the information about the history of the project.
 264
 265In most of the following, examples will be taken from one of the two
 266repositories above.
 267
 268How to check out a different version of a project
 269-------------------------------------------------
 270
 271Git is best thought of as a tool for storing the history of a
 272collection of files.  It stores the history as a compressed
 273collection of interrelated snapshots (versions) of the project's
 274contents.
 275
 276A single git repository may contain multiple branches.  Each branch
 277is a bookmark referencing a particular point in the project history.
 278The gitlink:git-branch[1] command shows you the list of branches:
 279
 280------------------------------------------------
 281$ git branch
 282* master
 283------------------------------------------------
 284
 285A freshly cloned repository contains a single branch, named "master",
 286and the working directory contains the version of the project
 287referred to by the master branch.
 288
 289Most projects also use tags.  Tags, like branches, are references
 290into the project's history, and can be listed using the
 291gitlink:git-tag[1] command:
 292
 293------------------------------------------------
 294$ git tag -l
 295v2.6.11
 296v2.6.11-tree
 297v2.6.12
 298v2.6.12-rc2
 299v2.6.12-rc3
 300v2.6.12-rc4
 301v2.6.12-rc5
 302v2.6.12-rc6
 303v2.6.13
 304...
 305------------------------------------------------
 306
 307Tags are expected to always point at the same version of a project,
 308while branches are expected to advance as development progresses.
 309
 310Create a new branch pointing to one of these versions and check it
 311out using gitlink:git-checkout[1]:
 312
 313------------------------------------------------
 314$ git checkout -b new v2.6.13
 315------------------------------------------------
 316
 317The working directory then reflects the contents that the project had
 318when it was tagged v2.6.13, and gitlink:git-branch[1] shows two
 319branches, with an asterisk marking the currently checked-out branch:
 320
 321------------------------------------------------
 322$ git branch
 323  master
 324* new
 325------------------------------------------------
 326
 327If you decide that you'd rather see version 2.6.17, you can modify
 328the current branch to point at v2.6.17 instead, with
 329
 330------------------------------------------------
 331$ git reset --hard v2.6.17
 332------------------------------------------------
 333
 334Note that if the current branch was your only reference to a
 335particular point in history, then resetting that branch may leave you
 336with no way to find the history it used to point to; so use this
 337command carefully.
 338
 339Understanding History: Commits
 340------------------------------
 341
 342Every change in the history of a project is represented by a commit.
 343The gitlink:git-show[1] command shows the most recent commit on the
 344current branch:
 345
 346------------------------------------------------
 347$ git show
 348commit 2b5f6dcce5bf94b9b119e9ed8d537098ec61c3d2
 349Author: Jamal Hadi Salim <hadi@cyberus.ca>
 350Date:   Sat Dec 2 22:22:25 2006 -0800
 351
 352    [XFRM]: Fix aevent structuring to be more complete.
 353    
 354    aevents can not uniquely identify an SA. We break the ABI with this
 355    patch, but consensus is that since it is not yet utilized by any
 356    (known) application then it is fine (better do it now than later).
 357    
 358    Signed-off-by: Jamal Hadi Salim <hadi@cyberus.ca>
 359    Signed-off-by: David S. Miller <davem@davemloft.net>
 360
 361diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt
 362index 8be626f..d7aac9d 100644
 363--- a/Documentation/networking/xfrm_sync.txt
 364+++ b/Documentation/networking/xfrm_sync.txt
 365@@ -47,10 +47,13 @@ aevent_id structure looks like:
 366 
 367    struct xfrm_aevent_id {
 368              struct xfrm_usersa_id           sa_id;
 369+             xfrm_address_t                  saddr;
 370              __u32                           flags;
 371+             __u32                           reqid;
 372    };
 373...
 374------------------------------------------------
 375
 376As you can see, a commit shows who made the latest change, what they
 377did, and why.
 378
 379Every commit has a 40-hexdigit id, sometimes called the "SHA1 id", shown
 380on the first line of the "git show" output.  You can usually refer to
 381a commit by a shorter name, such as a tag or a branch name, but this
 382longer id can also be useful.  In particular, it is a globally unique
 383name for this commit: so if you tell somebody else the SHA1 id (for
 384example in email), then you are guaranteed they will see the same
 385commit in their repository that you do in yours.
 386
 387Understanding history: commits, parents, and reachability
 388~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 389
 390Every commit (except the very first commit in a project) also has a
 391parent commit which shows what happened before this commit.
 392Following the chain of parents will eventually take you back to the
 393beginning of the project.
 394
 395However, the commits do not form a simple list; git allows lines of
 396development to diverge and then reconverge, and the point where two
 397lines of development reconverge is called a "merge".  The commit
 398representing a merge can therefore have more than one parent, with
 399each parent representing the most recent commit on one of the lines
 400of development leading to that point.
 401
 402The best way to see how this works is using the gitlink:gitk[1]
 403command; running gitk now on a git repository and looking for merge
 404commits will help understand how the git organizes history.
 405
 406In the following, we say that commit X is "reachable" from commit Y
 407if commit X is an ancestor of commit Y.  Equivalently, you could say
 408that Y is a descendent of X, or that there is a chain of parents
 409leading from commit Y to commit X.
 410
 411Undestanding history: History diagrams
 412~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 413
 414We will sometimes represent git history using diagrams like the one
 415below.  Commits are shown as "o", and the links between them with
 416lines drawn with - / and \.  Time goes left to right:
 417
 418         o--o--o <-- Branch A
 419        /
 420 o--o--o <-- master
 421        \
 422         o--o--o <-- Branch B
 423
 424If we need to talk about a particular commit, the character "o" may
 425be replaced with another letter or number.
 426
 427Understanding history: What is a branch?
 428~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 429
 430Though we've been using the word "branch" to mean a kind of reference
 431to a particular commit, the word branch is also commonly used to
 432refer to the line of commits leading up to that point.  In the
 433example above, git may think of the branch named "A" as just a
 434pointer to one particular commit, but we may refer informally to the
 435line of three commits leading up to that point as all being part of
 436"branch A".
 437
 438If we need to make it clear that we're just talking about the most
 439recent commit on the branch, we may refer to that commit as the
 440"head" of the branch.
 441
 442Manipulating branches
 443---------------------
 444
 445Creating, deleting, and modifying branches is quick and easy; here's
 446a summary of the commands:
 447
 448git branch::
 449        list all branches
 450git branch <branch>::
 451        create a new branch named <branch>, referencing the same
 452        point in history as the current branch
 453git branch <branch> <start-point>::
 454        create a new branch named <branch>, referencing
 455        <start-point>, which may be specified any way you like,
 456        including using a branch name or a tag name
 457git branch -d <branch>::
 458        delete the branch <branch>; if the branch you are deleting
 459        points to a commit which is not reachable from this branch,
 460        this command will fail with a warning.
 461git branch -D <branch>::
 462        even if the branch points to a commit not reachable
 463        from the current branch, you may know that that commit
 464        is still reachable from some other branch or tag.  In that
 465        case it is safe to use this command to force git to delete
 466        the branch.
 467git checkout <branch>::
 468        make the current branch <branch>, updating the working
 469        directory to reflect the version referenced by <branch>
 470git checkout -b <new> <start-point>::
 471        create a new branch <new> referencing <start-point>, and
 472        check it out.
 473
 474It is also useful to know that the special symbol "HEAD" can always
 475be used to refer to the current branch.
 476
 477Examining branches from a remote repository
 478-------------------------------------------
 479
 480The "master" branch that was created at the time you cloned is a copy
 481of the HEAD in the repository that you cloned from.  That repository
 482may also have had other branches, though, and your local repository
 483keeps branches which track each of those remote branches, which you
 484can view using the "-r" option to gitlink:git-branch[1]:
 485
 486------------------------------------------------
 487$ git branch -r
 488  origin/HEAD
 489  origin/html
 490  origin/maint
 491  origin/man
 492  origin/master
 493  origin/next
 494  origin/pu
 495  origin/todo
 496------------------------------------------------
 497
 498You cannot check out these remote-tracking branches, but you can
 499examine them on a branch of your own, just as you would a tag:
 500
 501------------------------------------------------
 502$ git checkout -b my-todo-copy origin/todo
 503------------------------------------------------
 504
 505Note that the name "origin" is just the name that git uses by default
 506to refer to the repository that you cloned from.
 507
 508[[how-git-stores-references]]
 509How git stores references
 510-------------------------
 511
 512Branches, remote-tracking branches, and tags are all references to
 513commits.  Git stores these references in the ".git" directory.  Most
 514of them are stored in .git/refs/:
 515
 516        - branches are stored in .git/refs/heads
 517        - tags are stored in .git/refs/tags
 518        - remote-tracking branches for "origin" are stored in
 519          .git/refs/remotes/origin/
 520
 521If you look at one of these files you will see that they usually
 522contain just the SHA1 id of a commit:
 523
 524------------------------------------------------
 525$ ls .git/refs/heads/
 526master
 527$ cat .git/refs/heads/master
 528c0f982dcf188d55db9d932a39d4ea7becaa55fed
 529------------------------------------------------
 530
 531You can refer to a reference by its path relative to the .git
 532directory.  However, we've seen above that git will also accept
 533shorter names; for example, "master" is an acceptable shortcut for
 534"refs/heads/master", and "origin/master" is a shortcut for
 535"refs/remotes/origin/master".
 536
 537As another useful shortcut, you can also refer to the "HEAD" of
 538"origin" (or any other remote), using just the name of the remote.
 539
 540For the complete list of paths which git checks for references, and
 541how it decides which to choose when there are multiple references
 542with the same name, see the "SPECIFYING REVISIONS" section of
 543gitlink:git-rev-parse[1].
 544
 545[[Updating-a-repository-with-git-fetch]]
 546Updating a repository with git fetch
 547------------------------------------
 548
 549Eventually the developer cloned from will do additional work in her
 550repository, creating new commits and advancing the branches to point
 551at the new commits.
 552
 553The command "git fetch", with no arguments, will update all of the
 554remote-tracking branches to the latest version found in her
 555repository.  It will not touch any of your own branches--not even the
 556"master" branch that was created for you on clone.
 557
 558Fetching branches from other repositories
 559-----------------------------------------
 560
 561You can also track branches from repositories other than the one you
 562cloned from, using gitlink:git-remote[1]:
 563
 564-------------------------------------------------
 565$ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git
 566$ git fetch
 567* refs/remotes/linux-nfs/master: storing branch 'master' ...
 568  commit: bf81b46
 569-------------------------------------------------
 570
 571New remote-tracking branches will be stored under the shorthand name
 572that you gave "git remote add", in this case linux-nfs:
 573
 574-------------------------------------------------
 575$ git branch -r
 576linux-nfs/master
 577origin/master
 578-------------------------------------------------
 579
 580If you run "git fetch <remote>" later, the tracking branches for the
 581named <remote> will be updated.
 582
 583If you examine the file .git/config, you will see that git has added
 584a new stanza:
 585
 586-------------------------------------------------
 587$ cat .git/config
 588...
 589[remote "linux-nfs"]
 590        url = git://linux-nfs.org/~bfields/git.git
 591        fetch = +refs/heads/*:refs/remotes/linux-nfs-read/*
 592...
 593-------------------------------------------------
 594
 595This is what causes git to track the remote's branches; you may
 596modify or delete these configuration options by editing .git/config
 597with a text editor.
 598
 599Fetching individual branches
 600----------------------------
 601
 602TODO: find another home for this, later on:
 603
 604You can also choose to update just one branch at a time:
 605
 606-------------------------------------------------
 607$ git fetch origin todo:refs/remotes/origin/todo
 608-------------------------------------------------
 609
 610The first argument, "origin", just tells git to fetch from the
 611repository you originally cloned from.  The second argument tells git
 612to fetch the branch named "todo" from the remote repository, and to
 613store it locally under the name refs/remotes/origin/todo; as we saw
 614above, remote-tracking branches are stored under
 615refs/remotes/<name-of-repository>/<name-of-branch>.
 616
 617You can also fetch branches from other repositories; so
 618
 619-------------------------------------------------
 620$ git fetch git://example.com/proj.git master:refs/remotes/example/master
 621-------------------------------------------------
 622
 623will create a new reference named "refs/remotes/example/master" and
 624store in it the branch named "master" from the repository at the
 625given URL.  If you already have a branch named
 626"refs/remotes/example/master", it will attempt to "fast-forward" to
 627the commit given by example.com's master branch.  So next we explain
 628what a fast-forward is:
 629
 630[[fast-forwards]]
 631Understanding git history: fast-forwards
 632----------------------------------------
 633
 634In the previous example, when updating an existing branch, "git
 635fetch" checks to make sure that the most recent commit on the remote
 636branch is a descendant of the most recent commit on your copy of the
 637branch before updating your copy of the branch to point at the new
 638commit.  Git calls this process a "fast forward".
 639
 640A fast forward looks something like this:
 641
 642 o--o--o--o <-- old head of the branch
 643           \
 644            o--o--o <-- new head of the branch
 645
 646
 647In some cases it is possible that the new head will *not* actually be
 648a descendant of the old head.  For example, the developer may have
 649realized she made a serious mistake, and decided to backtrack,
 650resulting in a situation like:
 651
 652 o--o--o--o--a--b <-- old head of the branch
 653           \
 654            o--o--o <-- new head of the branch
 655
 656
 657
 658In this case, "git fetch" will fail, and print out a warning.
 659
 660In that case, you can still force git to update to the new head, as
 661described in the following section.  However, note that in the
 662situation above this may mean losing the commits labeled "a" and "b",
 663unless you've already created a reference of your own pointing to
 664them.
 665
 666Forcing git fetch to do non-fast-forward updates
 667------------------------------------------------
 668
 669If git fetch fails because the new head of a branch is not a
 670descendant of the old head, you may force the update with:
 671
 672-------------------------------------------------
 673$ git fetch git://example.com/proj.git +master:refs/remotes/example/master
 674-------------------------------------------------
 675
 676Note the addition of the "+" sign.  Be aware that commits which the
 677old version of example/master pointed at may be lost, as we saw in
 678the previous section.
 679
 680Configuring remote branches
 681---------------------------
 682
 683We saw above that "origin" is just a shortcut to refer to the
 684repository which you originally cloned from.  This information is
 685stored in git configuration variables, which you can see using
 686gitlink:git-repo-config[1]:
 687
 688-------------------------------------------------
 689$ git-repo-config -l
 690core.repositoryformatversion=0
 691core.filemode=true
 692core.logallrefupdates=true
 693remote.origin.url=git://git.kernel.org/pub/scm/git/git.git
 694remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
 695branch.master.remote=origin
 696branch.master.merge=refs/heads/master
 697-------------------------------------------------
 698
 699If there are other repositories that you also use frequently, you can
 700create similar configuration options to save typing; for example,
 701after
 702
 703-------------------------------------------------
 704$ git repo-config remote.example.url git://example.com/proj.git
 705-------------------------------------------------
 706
 707then the following two commands will do the same thing:
 708
 709-------------------------------------------------
 710$ git fetch git://example.com/proj.git master:refs/remotes/example/master
 711$ git fetch example master:refs/remotes/example/master
 712-------------------------------------------------
 713
 714Even better, if you add one more option:
 715
 716-------------------------------------------------
 717$ git repo-config remote.example.fetch master:refs/remotes/example/master
 718-------------------------------------------------
 719
 720then the following commands will all do the same thing:
 721
 722-------------------------------------------------
 723$ git fetch git://example.com/proj.git master:ref/remotes/example/master
 724$ git fetch example master:ref/remotes/example/master
 725$ git fetch example example/master
 726$ git fetch example
 727-------------------------------------------------
 728
 729You can also add a "+" to force the update each time:
 730
 731-------------------------------------------------
 732$ git repo-config remote.example.fetch +master:ref/remotes/example/master
 733-------------------------------------------------
 734
 735Don't do this unless you're sure you won't mind "git fetch" possibly
 736throwing away commits on mybranch.
 737
 738Also note that all of the above configuration can be performed by
 739directly editing the file .git/config instead of using
 740gitlink:git-repo-config[1].
 741
 742See gitlink:git-repo-config[1] for more details on the configuration
 743options mentioned above.
 744
 745Exploring git history
 746=====================
 747
 748Git is best thought of as a tool for storing the history of a
 749collection of files.  It does this by storing compressed snapshots of
 750the contents of a file heirarchy, together with "commits" which show
 751the relationships between these snapshots.
 752
 753Git provides extremely flexible and fast tools for exploring the
 754history of a project.
 755
 756We start with one specialized tool which is useful for finding the
 757commit that introduced a bug into a project.
 758
 759How to use bisect to find a regression
 760--------------------------------------
 761
 762Suppose version 2.6.18 of your project worked, but the version at
 763"master" crashes.  Sometimes the best way to find the cause of such a
 764regression is to perform a brute-force search through the project's
 765history to find the particular commit that caused the problem.  The
 766gitlink:git-bisect[1] command can help you do this:
 767
 768-------------------------------------------------
 769$ git bisect start
 770$ git bisect good v2.6.18
 771$ git bisect bad master
 772Bisecting: 3537 revisions left to test after this
 773[65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
 774-------------------------------------------------
 775
 776If you run "git branch" at this point, you'll see that git has
 777temporarily moved you to a new branch named "bisect".  This branch
 778points to a commit (with commit id 65934...) that is reachable from
 779v2.6.19 but not from v2.6.18.  Compile and test it, and see whether
 780it crashes.  Assume it does crash.  Then:
 781
 782-------------------------------------------------
 783$ git bisect bad
 784Bisecting: 1769 revisions left to test after this
 785[7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings
 786-------------------------------------------------
 787
 788checks out an older version.  Continue like this, telling git at each
 789stage whether the version it gives you is good or bad, and notice
 790that the number of revisions left to test is cut approximately in
 791half each time.
 792
 793After about 13 tests (in this case), it will output the commit id of
 794the guilty commit.  You can then examine the commit with
 795gitlink:git-show[1], find out who wrote it, and mail them your bug
 796report with the commit id.  Finally, run
 797
 798-------------------------------------------------
 799$ git bisect reset
 800-------------------------------------------------
 801
 802to return you to the branch you were on before and delete the
 803temporary "bisect" branch.
 804
 805Note that the version which git-bisect checks out for you at each
 806point is just a suggestion, and you're free to try a different
 807version if you think it would be a good idea.  For example,
 808occasionally you may land on a commit that broke something unrelated;
 809run
 810
 811-------------------------------------------------
 812$ git bisect-visualize
 813-------------------------------------------------
 814
 815which will run gitk and label the commit it chose with a marker that
 816says "bisect".  Chose a safe-looking commit nearby, note its commit
 817id, and check it out with:
 818
 819-------------------------------------------------
 820$ git reset --hard fb47ddb2db...
 821-------------------------------------------------
 822
 823then test, run "bisect good" or "bisect bad" as appropriate, and
 824continue.
 825
 826Naming commits
 827--------------
 828
 829We have seen several ways of naming commits already:
 830
 831        - 40-hexdigit SHA1 id
 832        - branch name: refers to the commit at the head of the given
 833          branch
 834        - tag name: refers to the commit pointed to by the given tag
 835          (we've seen branches and tags are special cases of
 836          <<how-git-stores-references,references>>).
 837        - HEAD: refers to the head of the current branch
 838
 839There are many more; see the "SPECIFYING REVISIONS" section of the
 840gitlink:git-rev-parse[1] man page for the complete list of ways to
 841name revisions.  Some examples:
 842
 843-------------------------------------------------
 844$ git show fb47ddb2 # the first few characters of the SHA1 id
 845                    # are usually enough to specify it uniquely
 846$ git show HEAD^    # the parent of the HEAD commit
 847$ git show HEAD^^   # the grandparent
 848$ git show HEAD~4   # the great-great-grandparent
 849-------------------------------------------------
 850
 851Recall that merge commits may have more than one parent; by default,
 852^ and ~ follow the first parent listed in the commit, but you can
 853also choose:
 854
 855-------------------------------------------------
 856$ git show HEAD^1   # show the first parent of HEAD
 857$ git show HEAD^2   # show the second parent of HEAD
 858-------------------------------------------------
 859
 860In addition to HEAD, there are several other special names for
 861commits:
 862
 863Merges (to be discussed later), as well as operations such as
 864git-reset, which change the currently checked-out commit, generally
 865set ORIG_HEAD to the value HEAD had before the current operation.
 866
 867The git-fetch operation always stores the head of the last fetched
 868branch in FETCH_HEAD.  For example, if you run git fetch without
 869specifying a local branch as the target of the operation
 870
 871-------------------------------------------------
 872$ git fetch git://example.com/proj.git theirbranch
 873-------------------------------------------------
 874
 875the fetched commits will still be available from FETCH_HEAD.
 876
 877When we discuss merges we'll also see the special name MERGE_HEAD,
 878which refers to the other branch that we're merging in to the current
 879branch.
 880
 881The gitlink:git-rev-parse[1] command is a low-level command that is
 882occasionally useful for translating some name for a commit to the SHA1 id for
 883that commit:
 884
 885-------------------------------------------------
 886$ git rev-parse origin
 887e05db0fd4f31dde7005f075a84f96b360d05984b
 888-------------------------------------------------
 889
 890Creating tags
 891-------------
 892
 893We can also create a tag to refer to a particular commit; after
 894running
 895
 896-------------------------------------------------
 897$ git-tag stable-1 1b2e1d63ff
 898-------------------------------------------------
 899
 900You can use stable-1 to refer to the commit 1b2e1d63ff.
 901
 902This creates a "lightweight" tag.  If the tag is a tag you wish to
 903share with others, and possibly sign cryptographically, then you
 904should create a tag object instead; see the gitlink:git-tag[1] man
 905page for details.
 906
 907Browsing revisions
 908------------------
 909
 910The gitlink:git-log[1] command can show lists of commits.  On its
 911own, it shows all commits reachable from the parent commit; but you
 912can also make more specific requests:
 913
 914-------------------------------------------------
 915$ git log v2.5..        # commits since (not reachable from) v2.5
 916$ git log test..master  # commits reachable from master but not test
 917$ git log master..test  # ...reachable from test but not master
 918$ git log master...test # ...reachable from either test or master,
 919                        #    but not both
 920$ git log --since="2 weeks ago" # commits from the last 2 weeks
 921$ git log Makefile      # commits which modify Makefile
 922$ git log fs/           # ... which modify any file under fs/
 923$ git log -S'foo()'     # commits which add or remove any file data
 924                        # matching the string 'foo()'
 925-------------------------------------------------
 926
 927And of course you can combine all of these; the following finds
 928commits since v2.5 which touch the Makefile or any file under fs:
 929
 930-------------------------------------------------
 931$ git log v2.5.. Makefile fs/
 932-------------------------------------------------
 933
 934You can also ask git log to show patches:
 935
 936-------------------------------------------------
 937$ git log -p
 938-------------------------------------------------
 939
 940See the "--pretty" option in the gitlink:git-log[1] man page for more
 941display options.
 942
 943Note that git log starts with the most recent commit and works
 944backwards through the parents; however, since git history can contain
 945multiple independant lines of development, the particular order that
 946commits are listed in may be somewhat arbitrary.
 947
 948Generating diffs
 949----------------
 950
 951You can generate diffs between any two versions using
 952gitlink:git-diff[1]:
 953
 954-------------------------------------------------
 955$ git diff master..test
 956-------------------------------------------------
 957
 958Sometimes what you want instead is a set of patches:
 959
 960-------------------------------------------------
 961$ git format-patch master..test
 962-------------------------------------------------
 963
 964will generate a file with a patch for each commit reachable from test
 965but not from master.  Note that if master also has commits which are
 966not reachable from test, then the combined result of these patches
 967will not be the same as the diff produced by the git-diff example.
 968
 969Viewing old file versions
 970-------------------------
 971
 972You can always view an old version of a file by just checking out the
 973correct revision first.  But sometimes it is more convenient to be
 974able to view an old version of a single file without checking
 975anything out; this command does that:
 976
 977-------------------------------------------------
 978$ git show v2.5:fs/locks.c
 979-------------------------------------------------
 980
 981Before the colon may be anything that names a commit, and after it
 982may be any path to a file tracked by git.
 983
 984Examples
 985--------
 986
 987Check whether two branches point at the same history
 988~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 989
 990Suppose you want to check whether two branches point at the same point
 991in history.
 992
 993-------------------------------------------------
 994$ git diff origin..master
 995-------------------------------------------------
 996
 997will tell you whether the contents of the project are the same at the
 998two branches; in theory, however, it's possible that the same project
 999contents could have been arrived at by two different historical
1000routes.  You could compare the SHA1 id's:
1001
1002-------------------------------------------------
1003$ git rev-list origin
1004e05db0fd4f31dde7005f075a84f96b360d05984b
1005$ git rev-list master
1006e05db0fd4f31dde7005f075a84f96b360d05984b
1007-------------------------------------------------
1008
1009Or you could recall that the ... operator selects all commits
1010contained reachable from either one reference or the other but not
1011both: so
1012
1013-------------------------------------------------
1014$ git log origin...master
1015-------------------------------------------------
1016
1017will return no commits when the two branches are equal.
1018
1019Check which tagged version a given fix was first included in
1020~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1021
1022Suppose you know that the commit e05db0fd fixed a certain problem.
1023You'd like to find the earliest tagged release that contains that
1024fix.
1025
1026Of course, there may be more than one answer--if the history branched
1027after commit e05db0fd, then there could be multiple "earliest" tagged
1028releases.
1029
1030You could just visually inspect the commits since e05db0fd:
1031
1032-------------------------------------------------
1033$ gitk e05db0fd..
1034-------------------------------------------------
1035
1036...
1037
1038Developing with git
1039===================
1040
1041Telling git your name
1042---------------------
1043
1044Before creating any commits, you should introduce yourself to git.  The
1045easiest way to do so is:
1046
1047------------------------------------------------
1048$ cat >~/.gitconfig <<\EOF
1049[user]
1050        name = Your Name Comes Here
1051        email = you@yourdomain.example.com
1052EOF
1053------------------------------------------------
1054
1055
1056Creating a new repository
1057-------------------------
1058
1059Creating a new repository from scratch is very easy:
1060
1061-------------------------------------------------
1062$ mkdir project
1063$ cd project
1064$ git init
1065-------------------------------------------------
1066
1067If you have some initial content (say, a tarball):
1068
1069-------------------------------------------------
1070$ tar -xzvf project.tar.gz
1071$ cd project
1072$ git init
1073$ git add . # include everything below ./ in the first commit:
1074$ git commit
1075-------------------------------------------------
1076
1077[[how-to-make-a-commit]]
1078how to make a commit
1079--------------------
1080
1081Creating a new commit takes three steps:
1082
1083        1. Making some changes to the working directory using your
1084           favorite editor.
1085        2. Telling git about your changes.
1086        3. Creating the commit using the content you told git about
1087           in step 2.
1088
1089In practice, you can interleave and repeat steps 1 and 2 as many
1090times as you want: in order to keep track of what you want committed
1091at step 3, git maintains a snapshot of the tree's contents in a
1092special staging area called "the index."
1093
1094At the beginning, the content of the index will be identical to
1095that of the HEAD.  The command "git diff --cached", which shows
1096the difference between the HEAD and the index, should therefore
1097produce no output at that point.
1098
1099Modifying the index is easy:
1100
1101To update the index with the new contents of a modified file, use
1102
1103-------------------------------------------------
1104$ git add path/to/file
1105-------------------------------------------------
1106
1107To add the contents of a new file to the index, use
1108
1109-------------------------------------------------
1110$ git add path/to/file
1111-------------------------------------------------
1112
1113To remove a file from the index and from the working tree,
1114
1115-------------------------------------------------
1116$ git rm path/to/file
1117-------------------------------------------------
1118
1119After each step you can verify that
1120
1121-------------------------------------------------
1122$ git diff --cached
1123-------------------------------------------------
1124
1125always shows the difference between the HEAD and the index file--this
1126is what you'd commit if you created the commit now--and that
1127
1128-------------------------------------------------
1129$ git diff
1130-------------------------------------------------
1131
1132shows the difference between the working tree and the index file.
1133
1134Note that "git add" always adds just the current contents of a file
1135to the index; further changes to the same file will be ignored unless
1136you run git-add on the file again.
1137
1138When you're ready, just run
1139
1140-------------------------------------------------
1141$ git commit
1142-------------------------------------------------
1143
1144and git will prompt you for a commit message and then create the new
1145commmit.  Check to make sure it looks like what you expected with
1146
1147-------------------------------------------------
1148$ git show
1149-------------------------------------------------
1150
1151As a special shortcut,
1152                
1153-------------------------------------------------
1154$ git commit -a
1155-------------------------------------------------
1156
1157will update the index with any files that you've modified or removed
1158and create a commit, all in one step.
1159
1160A number of commands are useful for keeping track of what you're
1161about to commit:
1162
1163-------------------------------------------------
1164$ git diff --cached # difference between HEAD and the index; what
1165                    # would be commited if you ran "commit" now.
1166$ git diff          # difference between the index file and your
1167                    # working directory; changes that would not
1168                    # be included if you ran "commit" now.
1169$ git status        # a brief per-file summary of the above.
1170-------------------------------------------------
1171
1172creating good commit messages
1173-----------------------------
1174
1175Though not required, it's a good idea to begin the commit message
1176with a single short (less than 50 character) line summarizing the
1177change, followed by a blank line and then a more thorough
1178description.  Tools that turn commits into email, for example, use
1179the first line on the Subject line and the rest of the commit in the
1180body.
1181
1182how to merge
1183------------
1184
1185You can rejoin two diverging branches of development using
1186gitlink:git-merge[1]:
1187
1188-------------------------------------------------
1189$ git merge branchname
1190-------------------------------------------------
1191
1192merges the development in the branch "branchname" into the current
1193branch.  If there are conflicts--for example, if the same file is
1194modified in two different ways in the remote branch and the local
1195branch--then you are warned; the output may look something like this:
1196
1197-------------------------------------------------
1198$ git pull . next
1199Trying really trivial in-index merge...
1200fatal: Merge requires file-level merging
1201Nope.
1202Merging HEAD with 77976da35a11db4580b80ae27e8d65caf5208086
1203Merging:
120415e2162 world
120577976da goodbye
1206found 1 common ancestor(s):
1207d122ed4 initial
1208Auto-merging file.txt
1209CONFLICT (content): Merge conflict in file.txt
1210Automatic merge failed; fix conflicts and then commit the result.
1211-------------------------------------------------
1212
1213Conflict markers are left in the problematic files, and after
1214you resolve the conflicts manually, you can update the index
1215with the contents and run git commit, as you normally would when
1216creating a new file.
1217
1218If you examine the resulting commit using gitk, you will see that it
1219has two parents, one pointing to the top of the current branch, and
1220one to the top of the other branch.
1221
1222In more detail:
1223
1224[[resolving-a-merge]]
1225Resolving a merge
1226-----------------
1227
1228When a merge isn't resolved automatically, git leaves the index and
1229the working tree in a special state that gives you all the
1230information you need to help resolve the merge.
1231
1232Files with conflicts are marked specially in the index, so until you
1233resolve the problem and update the index, git commit will fail:
1234
1235-------------------------------------------------
1236$ git commit
1237file.txt: needs merge
1238-------------------------------------------------
1239
1240Also, git status will list those files as "unmerged".
1241
1242All of the changes that git was able to merge automatically are
1243already added to the index file, so gitlink:git-diff[1] shows only
1244the conflicts.  Also, it uses a somewhat unusual syntax:
1245
1246-------------------------------------------------
1247$ git diff
1248diff --cc file.txt
1249index 802992c,2b60207..0000000
1250--- a/file.txt
1251+++ b/file.txt
1252@@@ -1,1 -1,1 +1,5 @@@
1253++<<<<<<< HEAD:file.txt
1254 +Hello world
1255++=======
1256+ Goodbye
1257++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1258-------------------------------------------------
1259
1260Recall that the commit which will be commited after we resolve this
1261conflict will have two parents instead of the usual one: one parent
1262will be HEAD, the tip of the current branch; the other will be the
1263tip of the other branch, which is stored temporarily in MERGE_HEAD.
1264
1265The diff above shows the differences between the working-tree version
1266of file.txt and two previous version: one version from HEAD, and one
1267from MERGE_HEAD.  So instead of preceding each line by a single "+"
1268or "-", it now uses two columns: the first column is used for
1269differences between the first parent and the working directory copy,
1270and the second for differences between the second parent and the
1271working directory copy.  Thus after resolving the conflict in the
1272obvious way, the diff will look like:
1273
1274-------------------------------------------------
1275$ git diff
1276diff --cc file.txt
1277index 802992c,2b60207..0000000
1278--- a/file.txt
1279+++ b/file.txt
1280@@@ -1,1 -1,1 +1,1 @@@
1281- Hello world
1282 -Goodbye
1283++Goodbye world
1284-------------------------------------------------
1285
1286This shows that our resolved version deleted "Hello world" from the
1287first parent, deleted "Goodbye" from the second parent, and added
1288"Goodbye world", which was previously absent from both.
1289
1290The gitlink:git-log[1] command also provides special help for merges:
1291
1292-------------------------------------------------
1293$ git log --merge
1294-------------------------------------------------
1295
1296This will list all commits which exist only on HEAD or on MERGE_HEAD,
1297and which touch an unmerged file.
1298
1299We can now add the resolved version to the index and commit:
1300
1301-------------------------------------------------
1302$ git add file.txt
1303$ git commit
1304-------------------------------------------------
1305
1306Note that the commit message will already be filled in for you with
1307some information about the merge.  Normally you can just use this
1308default message unchanged, but you may add additional commentary of
1309your own if desired.
1310
1311[[undoing-a-merge]]
1312undoing a merge
1313---------------
1314
1315If you get stuck and decide to just give up and throw the whole mess
1316away, you can always return to the pre-merge state with
1317
1318-------------------------------------------------
1319$ git reset --hard HEAD
1320-------------------------------------------------
1321
1322Or, if you've already commited the merge that you want to throw away,
1323
1324-------------------------------------------------
1325$ git reset --hard HEAD^
1326-------------------------------------------------
1327
1328However, this last command can be dangerous in some cases--never
1329throw away a commit you have already committed if that commit may
1330itself have been merged into another branch, as doing so may confuse
1331further merges.
1332
1333Fast-forward merges
1334-------------------
1335
1336There is one special case not mentioned above, which is treated
1337differently.  Normally, a merge results in a merge commit, with two
1338parents, one pointing at each of the two lines of development that
1339were merged.
1340
1341However, if one of the two lines of development is completely
1342contained within the other--so every commit present in the one is
1343already contained in the other--then git just performs a
1344<<fast-forwards,fast forward>>; the head of the current branch is
1345moved forward to point at the head of the merged-in branch, without
1346any new commits being created.
1347
1348Fixing mistakes
1349---------------
1350
1351If you've messed up the working tree, but haven't yet committed your
1352mistake, you can return the entire working tree to the last committed
1353state with
1354
1355-------------------------------------------------
1356$ git reset --hard HEAD
1357-------------------------------------------------
1358
1359If you make a commit that you later wish you hadn't, there are two
1360fundamentally different ways to fix the problem:
1361
1362        1. You can create a new commit that undoes whatever was done
1363        by the previous commit.  This is the correct thing if your
1364        mistake has already been made public.
1365
1366        2. You can go back and modify the old commit.  You should
1367        never do this if you have already made the history public;
1368        git does not normally expect the "history" of a project to
1369        change, and cannot correctly perform repeated merges from
1370        a branch that has had its history changed.
1371
1372Fixing a mistake with a new commit
1373~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1374
1375Creating a new commit that reverts an earlier change is very easy;
1376just pass the gitlink:git-revert[1] command a reference to the bad
1377commit; for example, to revert the most recent commit:
1378
1379-------------------------------------------------
1380$ git revert HEAD
1381-------------------------------------------------
1382
1383This will create a new commit which undoes the change in HEAD.  You
1384will be given a chance to edit the commit message for the new commit.
1385
1386You can also revert an earlier change, for example, the next-to-last:
1387
1388-------------------------------------------------
1389$ git revert HEAD^
1390-------------------------------------------------
1391
1392In this case git will attempt to undo the old change while leaving
1393intact any changes made since then.  If more recent changes overlap
1394with the changes to be reverted, then you will be asked to fix
1395conflicts manually, just as in the case of <<resolving-a-merge,
1396resolving a merge>>.
1397
1398Fixing a mistake by editing history
1399~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1400
1401If the problematic commit is the most recent commit, and you have not
1402yet made that commit public, then you may just
1403<<undoing-a-merge,destroy it using git-reset>>.
1404
1405Alternatively, you
1406can edit the working directory and update the index to fix your
1407mistake, just as if you were going to <<how-to-make-a-commit,create a
1408new commit>>, then run
1409
1410-------------------------------------------------
1411$ git commit --amend
1412-------------------------------------------------
1413
1414which will replace the old commit by a new commit incorporating your
1415changes, giving you a chance to edit the old commit message first.
1416
1417Again, you should never do this to a commit that may already have
1418been merged into another branch; use gitlink:git-revert[1] instead in
1419that case.
1420
1421It is also possible to edit commits further back in the history, but
1422this is an advanced topic to be left for
1423<<cleaning-up-history,another chapter>>.
1424
1425Checking out an old version of a file
1426~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1427
1428In the process of undoing a previous bad change, you may find it
1429useful to check out an older version of a particular file using
1430gitlink:git-checkout[1].  We've used git checkout before to switch
1431branches, but it has quite different behavior if it is given a path
1432name: the command
1433
1434-------------------------------------------------
1435$ git checkout HEAD^ path/to/file
1436-------------------------------------------------
1437
1438replaces path/to/file by the contents it had in the commit HEAD^, and
1439also updates the index to match.  It does not change branches.
1440
1441If you just want to look at an old version of the file, without
1442modifying the working directory, you can do that with
1443gitlink:git-show[1]:
1444
1445-------------------------------------------------
1446$ git show HEAD^ path/to/file
1447-------------------------------------------------
1448
1449which will display the given version of the file.
1450
1451Ensuring good performance
1452-------------------------
1453
1454On large repositories, git depends on compression to keep the history
1455information from taking up to much space on disk or in memory.
1456
1457This compression is not performed automatically.  Therefore you
1458should occasionally run
1459
1460-------------------------------------------------
1461$ git gc
1462-------------------------------------------------
1463
1464to recompress the archive and to prune any commits which are no
1465longer referred to anywhere.  This can be very time-consuming, and
1466you should not modify the repository while it is working, so you
1467should run it while you are not working.
1468
1469Sharing development with others
1470===============================
1471
1472[[getting-updates-with-git-pull]]
1473Getting updates with git pull
1474-----------------------------
1475
1476After you clone a repository and make a few changes of your own, you
1477may wish to check the original repository for updates and merge them
1478into your own work.
1479
1480We have already seen <<Updating-a-repository-with-git-fetch,how to
1481keep remote tracking branches up to date>> with gitlink:git-fetch[1],
1482and how to merge two branches.  So you can merge in changes from the
1483original repository's master branch with:
1484
1485-------------------------------------------------
1486$ git fetch
1487$ git merge origin/master
1488-------------------------------------------------
1489
1490However, the gitlink:git-pull[1] command provides a way to do this in
1491one step:
1492
1493-------------------------------------------------
1494$ git pull origin master
1495-------------------------------------------------
1496
1497In fact, "origin" is normally the default repository to pull from,
1498and the default branch is normally the HEAD of the remote repository,
1499so often you can accomplish the above with just
1500
1501-------------------------------------------------
1502$ git pull
1503-------------------------------------------------
1504
1505See the descriptions of the branch.<name>.remote and
1506branch.<name>.merge options in gitlink:git-repo-config[1] to learn
1507how to control these defaults depending on the current branch.
1508
1509In addition to saving you keystrokes, "git pull" also helps you by
1510producing a default commit message documenting the branch and
1511repository that you pulled from.
1512
1513(But note that no such commit will be created in the case of a
1514<<fast-forwards,fast forward>>; instead, your branch will just be
1515updated to point to the latest commit from the upstream branch).
1516
1517The git-pull command can also be given "." as the "remote" repository, in
1518which case it just merges in a branch from the current repository; so
1519the commands
1520
1521-------------------------------------------------
1522$ git pull . branch
1523$ git merge branch
1524-------------------------------------------------
1525
1526are roughly equivalent.  The former is actually very commonly used.
1527
1528Submitting patches to a project
1529-------------------------------
1530
1531If you just have a few changes, the simplest way to submit them may
1532just be to send them as patches in email:
1533
1534First, use gitlink:git-format-patches[1]; for example:
1535
1536-------------------------------------------------
1537$ git format-patch origin
1538-------------------------------------------------
1539
1540will produce a numbered series of files in the current directory, one
1541for each patch in the current branch but not in origin/HEAD.
1542
1543You can then import these into your mail client and send them by
1544hand.  However, if you have a lot to send at once, you may prefer to
1545use the gitlink:git-send-email[1] script to automate the process.
1546Consult the mailing list for your project first to determine how they
1547prefer such patches be handled.
1548
1549Importing patches to a project
1550------------------------------
1551
1552Git also provides a tool called gitlink:git-am[1] (am stands for
1553"apply mailbox"), for importing such an emailed series of patches.
1554Just save all of the patch-containing messages, in order, into a
1555single mailbox file, say "patches.mbox", then run
1556
1557-------------------------------------------------
1558$ git am -3 patches.mbox
1559-------------------------------------------------
1560
1561Git will apply each patch in order; if any conflicts are found, it
1562will stop, and you can fix the conflicts as described in
1563"<<resolving-a-merge,Resolving a merge>>".  (The "-3" option tells
1564git to perform a merge; if you would prefer it just to abort and
1565leave your tree and index untouched, you may omit that option.)
1566
1567Once the index is updated with the results of the conflict
1568resolution, instead of creating a new commit, just run
1569
1570-------------------------------------------------
1571$ git am --resolved
1572-------------------------------------------------
1573
1574and git will create the commit for you and continue applying the
1575remaining patches from the mailbox.
1576
1577The final result will be a series of commits, one for each patch in
1578the original mailbox, with authorship and commit log message each
1579taken from the message containing each patch.
1580
1581[[setting-up-a-public-repository]]
1582Setting up a public repository
1583------------------------------
1584
1585Another way to submit changes to a project is to simply tell the
1586maintainer of that project to pull from your repository, exactly as
1587you did in the section "<<getting-updates-with-git-pull, Getting
1588updates with git pull>>".
1589
1590If you and maintainer both have accounts on the same machine, then
1591then you can just pull changes from each other's repositories
1592directly; note that all of the command (gitlink:git-clone[1],
1593git-fetch[1], git-pull[1], etc.) which accept a URL as an argument
1594will also accept a local file patch; so, for example, you can
1595use
1596
1597-------------------------------------------------
1598$ git clone /path/to/repository
1599$ git pull /path/to/other/repository
1600-------------------------------------------------
1601
1602If this sort of setup is inconvenient or impossible, another (more
1603common) option is to set up a public repository on a public server.
1604This also allows you to cleanly separate private work in progress
1605from publicly visible work.
1606
1607You will continue to do your day-to-day work in your personal
1608repository, but periodically "push" changes from your personal
1609repository into your public repository, allowing other developers to
1610pull from that repository.  So the flow of changes, in a situation
1611where there is one other developer with a public repository, looks
1612like this:
1613
1614                        you push
1615  your personal repo ------------------> your public repo
1616        ^                                     |
1617        |                                     |
1618        | you pull                            | they pull
1619        |                                     |
1620        |                                     |
1621        |               they push             V
1622  their public repo <------------------- their repo
1623
1624Now, assume your personal repository is in the directory ~/proj.  We
1625first create a new clone of the repository:
1626
1627-------------------------------------------------
1628$ git clone --bare proj-clone.git
1629-------------------------------------------------
1630
1631The resulting directory proj-clone.git will contains a "bare" git
1632repository--it is just the contents of the ".git" directory, without
1633a checked-out copy of a working directory.
1634
1635Next, copy proj-clone.git to the server where you plan to host the
1636public repository.  You can use scp, rsync, or whatever is most
1637convenient.
1638
1639If somebody else maintains the public server, they may already have
1640set up a git service for you, and you may skip to the section
1641"<<pushing-changes-to-a-public-repository,Pushing changes to a public
1642repository>>", below.
1643
1644Otherwise, the following sections explain how to export your newly
1645created public repository:
1646
1647[[exporting-via-http]]
1648Exporting a git repository via http
1649-----------------------------------
1650
1651The git protocol gives better performance and reliability, but on a
1652host with a web server set up, http exports may be simpler to set up.
1653
1654All you need to do is place the newly created bare git repository in
1655a directory that is exported by the web server, and make some
1656adjustments to give web clients some extra information they need:
1657
1658-------------------------------------------------
1659$ mv proj.git /home/you/public_html/proj.git
1660$ cd proj.git
1661$ git update-server-info
1662$ chmod a+x hooks/post-update
1663-------------------------------------------------
1664
1665(For an explanation of the last two lines, see
1666gitlink:git-update-server-info[1], and the documentation
1667link:hooks.txt[Hooks used by git].)
1668
1669Advertise the url of proj.git.  Anybody else should then be able to
1670clone or pull from that url, for example with a commandline like:
1671
1672-------------------------------------------------
1673$ git clone http://yourserver.com/~you/proj.git
1674-------------------------------------------------
1675
1676(See also
1677link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]
1678for a slightly more sophisticated setup using WebDAV which also
1679allows pushing over http.)
1680
1681[[exporting-via-git]]
1682Exporting a git repository via the git protocol
1683-----------------------------------------------
1684
1685This is the preferred method.
1686
1687For now, we refer you to the gitlink:git-daemon[1] man page for
1688instructions.  (See especially the examples section.)
1689
1690[[pushing-changes-to-a-public-repository]]
1691Pushing changes to a public repository
1692--------------------------------------
1693
1694Note that the two techniques outline above (exporting via
1695<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
1696maintainers to fetch your latest changes, but they do not allow write
1697access, which you will need to update the public repository with the
1698latest changes created in your private repository.
1699
1700The simplest way to do this is using gitlink:git-push[1] and ssh; to
1701update the remote branch named "master" with the latest state of your
1702branch named "master", run
1703
1704-------------------------------------------------
1705$ git push ssh://yourserver.com/~you/proj.git master:master
1706-------------------------------------------------
1707
1708or just
1709
1710-------------------------------------------------
1711$ git push ssh://yourserver.com/~you/proj.git master
1712-------------------------------------------------
1713
1714As with git-fetch, git-push will complain if this does not result in
1715a <<fast-forwards,fast forward>>.  Normally this is a sign of
1716something wrong.  However, if you are sure you know what you're
1717doing, you may force git-push to perform the update anyway by
1718proceeding the branch name by a plus sign:
1719
1720-------------------------------------------------
1721$ git push ssh://yourserver.com/~you/proj.git +master
1722-------------------------------------------------
1723
1724As with git-fetch, you may also set up configuration options to
1725save typing; so, for example, after
1726
1727-------------------------------------------------
1728$ cat >.git/config <<EOF
1729[remote "public-repo"]
1730        url = ssh://yourserver.com/~you/proj.git
1731EOF
1732-------------------------------------------------
1733
1734you should be able to perform the above push with just
1735
1736-------------------------------------------------
1737$ git push public-repo master
1738-------------------------------------------------
1739
1740See the explanations of the remote.<name>.url, branch.<name>.remote,
1741and remote.<name>.push options in gitlink:git-repo-config[1] for
1742details.
1743
1744Setting up a shared repository
1745------------------------------
1746
1747Another way to collaborate is by using a model similar to that
1748commonly used in CVS, where several developers with special rights
1749all push to and pull from a single shared repository.  See
1750link:cvs-migration.txt[git for CVS users] for instructions on how to
1751set this up.
1752
1753Allow web browsing of a repository
1754----------------------------------
1755
1756TODO: Brief setup-instructions for gitweb
1757
1758Examples
1759--------
1760
1761TODO: topic branches, typical roles as in everyday.txt, ?
1762
1763
1764Working with other version control systems
1765==========================================
1766
1767TODO: CVS, Subversion, series-of-release-tarballs, ?
1768
1769[[cleaning-up-history]]
1770Rewriting history and maintaining patch series
1771==============================================
1772
1773Normally commits are only added to a project, never taken away or
1774replaced.  Git is designed with this assumption, and violating it will
1775cause git's merge machinery (for example) to do the wrong thing.
1776
1777However, there is a situation in which it can be useful to violate this
1778assumption.
1779
1780Creating the perfect patch series
1781---------------------------------
1782
1783Suppose you are a contributor to a large project, and you want to add a
1784complicated feature, and to present it to the other developers in a way
1785that makes it easy for them to read your changes, verify that they are
1786correct, and understand why you made each change.
1787
1788If you present all of your changes as a single patch (or commit), they may
1789find it is too much to digest all at once.
1790
1791If you present them with the entire history of your work, complete with
1792mistakes, corrections, and dead ends, they may be overwhelmed.
1793
1794So the ideal is usually to produce a series of patches such that:
1795
1796        1. Each patch can be applied in order.
1797
1798        2. Each patch includes a single logical change, together with a
1799           message explaining the change.
1800
1801        3. No patch introduces a regression: after applying any initial
1802           part of the series, the resulting project still compiles and
1803           works, and has no bugs that it didn't have before.
1804
1805        4. The complete series produces the same end result as your own
1806           (probably much messier!) development process did.
1807
1808We will introduce some tools that can help you do this, explain how to use
1809them, and then explain some of the problems that can arise because you are
1810rewriting history.
1811
1812Keeping a patch series up to date using git-rebase
1813--------------------------------------------------
1814
1815Suppose you have a series of commits in a branch "mywork", which
1816originally branched off from "origin".
1817
1818Suppose you create a branch "mywork" on a remote-tracking branch "origin",
1819and created some commits on top of it:
1820
1821-------------------------------------------------
1822$ git checkout -b mywork origin
1823$ vi file.txt
1824$ git commit
1825$ vi otherfile.txt
1826$ git commit
1827...
1828-------------------------------------------------
1829
1830You have performed no merges into mywork, so it is just a simple linear
1831sequence of patches on top of "origin":
1832
1833
1834 o--o--o <-- origin
1835        \
1836         o--o--o <-- mywork
1837
1838Some more interesting work has been done in the upstream project, and
1839"origin" has advanced:
1840
1841 o--o--O--o--o--o <-- origin
1842        \
1843         a--b--c <-- mywork
1844
1845At this point, you could use "pull" to merge your changes back in;
1846the result would create a new merge commit, like this:
1847
1848
1849 o--o--O--o--o--o <-- origin
1850        \        \
1851         a--b--c--m <-- mywork
1852 
1853However, if you prefer to keep the history in mywork a simple series of
1854commits without any merges, you may instead choose to use
1855gitlink:git-rebase[1]:
1856
1857-------------------------------------------------
1858$ git checkout mywork
1859$ git rebase origin
1860-------------------------------------------------
1861
1862This will remove each of your commits from mywork, temporarily saving them
1863as patches (in a directory named ".dotest"), update mywork to point at the
1864latest version of origin, then apply each of the saved patches to the new
1865mywork.  The result will look like:
1866
1867
1868 o--o--O--o--o--o <-- origin
1869                 \
1870                  a'--b'--c' <-- mywork
1871
1872In the process, it may discover conflicts.  In that case it will stop and
1873allow you to fix the conflicts as described in
1874"<<resolving-a-merge,Resolving a merge>>".
1875
1876XXX: no, maybe not: git diff doesn't produce very useful results, and there's
1877no MERGE_HEAD.
1878
1879Once the index is updated with
1880the results of the conflict resolution, instead of creating a new commit,
1881just run
1882
1883-------------------------------------------------
1884$ git rebase --continue
1885-------------------------------------------------
1886
1887and git will continue applying the rest of the patches.
1888
1889At any point you may use the --abort option to abort this process and
1890return mywork to the state it had before you started the rebase:
1891
1892-------------------------------------------------
1893$ git rebase --abort
1894-------------------------------------------------
1895
1896Reordering or selecting from a patch series
1897-------------------------------------------
1898
1899Given one existing commit, the gitlink:git-cherry-pick[1] command allows
1900you to apply the change introduced by that commit and create a new commit
1901that records it.
1902
1903This can be useful for modifying a patch series.
1904
1905TODO: elaborate
1906
1907Other tools
1908-----------
1909
1910There are numerous other tools, such as stgit, which exist for the purpose
1911of maintianing a patch series.  These are out of the scope of this manual.
1912
1913Problems with rewriting history
1914-------------------------------
1915
1916The primary problem with rewriting the history of a branch has to do with
1917merging.
1918
1919TODO: elaborate
1920
1921
1922Git internals
1923=============
1924
1925Architectural overview
1926----------------------
1927
1928TODO: Sources, README, core-tutorial, tutorial-2.txt, technical/
1929
1930Glossary of git terms
1931=====================
1932
1933include::glossary.txt[]
1934
1935Notes and todo list for this manual
1936===================================
1937
1938This is a work in progress.
1939
1940The basic requirements:
1941        - It must be readable in order, from beginning to end, by
1942          someone intelligent with a basic grasp of the unix
1943          commandline, but without any special knowledge of git.  If
1944          necessary, any other prerequisites should be specifically
1945          mentioned as they arise.
1946        - Whenever possible, section headings should clearly describe
1947          the task they explain how to do, in language that requires
1948          no more knowledge than necessary: for example, "importing
1949          patches into a project" rather than "the git-am command"
1950
1951Think about how to create a clear chapter dependency graph that will
1952allow people to get to important topics without necessarily reading
1953everything in between.
1954
1955Scan Documentation/ for other stuff left out; in particular:
1956        howto's
1957        README
1958        some of technical/?
1959        hooks
1960        etc.
1961
1962Scan email archives for other stuff left out
1963
1964Scan man pages to see if any assume more background than this manual
1965provides.
1966
1967Simplify beginning by suggesting disconnected head instead of
1968temporary branch creation.
1969
1970Explain how to refer to file stages in the "how to resolve a merge"
1971section: diff -1, -2, -3, --ours, --theirs :1:/path notation.  The
1972"git ls-files --unmerged --stage" thing is sorta useful too,
1973actually.  And note gitk --merge.  Also what's easiest way to see
1974common merge base?  Note also text where I claim rebase and am
1975conflicts are resolved like merges isn't generally true, at least by
1976default--fix.
1977
1978Add more good examples.  Entire sections of just cookbook examples
1979might be a good idea; maybe make an "advanced examples" section a
1980standard end-of-chapter section?
1981
1982Include cross-references to the glossary, where appropriate.
1983
1984Add quickstart as first chapter.
1985
1986To document:
1987        reflogs, git reflog expire
1988        shallow clones??  See draft 1.5.0 release notes for some documentation.