Merge branch 'jx/do-not-crash-receive-pack-wo-head'

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index efe6a026f132b040cc47d847bbdb4f284c2a0133..e269fb110835305633ccafa6aa87cf1f425f7b8c 100644 (file)
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -3,7 +3,7 @@ git-checkout(1)
 
 NAME
 ----
-git-checkout - Checkout a branch or paths to the working tree
+git-checkout - Switch branches or restore working tree files
 
 SYNOPSIS
 --------
@@ -89,6 +89,10 @@ Omitting <branch> detaches HEAD at the tip of the current branch.
        (i.e.  commit, tag or tree) to update the index for the given
        paths before updating the working tree.
 +
+'git checkout' with <paths> or `--patch` is used to restore modified or
+deleted paths to their original contents from the index or replace paths
+with the contents from a named <tree-ish> (most often a commit-ish).
++
 The index may contain unmerged entries because of a previous failed merge.
 By default, if you try to check out such an entry from the index, the
 checkout operation will fail and nothing will be checked out.
@@ -116,6 +120,21 @@ entries; instead, unmerged entries are ignored.
 --theirs::
        When checking out paths from the index, check out stage #2
        ('ours') or #3 ('theirs') for unmerged paths.
++
+Note that during `git rebase` and `git pull --rebase`, 'ours' and
+'theirs' may appear swapped; `--ours` gives the version from the
+branch the changes are rebased onto, while `--theirs` gives the
+version from the branch that holds your work that is being rebased.
++
+This is because `rebase` is used in a workflow that treats the
+history at the remote as the shared canonical one, and treats the
+work done on the branch you are rebasing as the third-party work to
+be integrated, and you are temporarily assuming the role of the
+keeper of the canonical history during the rebase.  As the keeper of
+the canonical history, you need to view the history from the remote
+as `ours` (i.e. "our shared canonical history"), while what you did
+on your side branch as `theirs` (i.e. "one contributor's work on top
+of it").
 
 -b <new_branch>::
        Create a new branch named <new_branch> and start it at
@@ -144,7 +163,7 @@ explicitly give a name with '-b' in such a case.
 
 --no-track::
        Do not set up "upstream" configuration, even if the
-       branch.autosetupmerge configuration variable is true.
+       branch.autoSetupMerge configuration variable is true.
 
 -l::
        Create the new branch's reflog; see linkgit:git-branch[1] for
@@ -210,7 +229,7 @@ the conflicted merge in the specified paths.
 --conflict=<style>::
        The same as --merge option above, but changes the way the
        conflicting hunks are presented, overriding the
-       merge.conflictstyle configuration variable.  Possible values are
+       merge.conflictStyle configuration variable.  Possible values are
        "merge" (default) and "diff3" (in addition to what is shown by
        "merge" style, shows the original contents).