SubmittingPatches: document how to reference previous commits

diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 67fa5ee19520a113bceb1a704ee84f40e8eb7693..a62a2a615d0e0146d538213571d7f41bd02488cf 100644 (file)
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -3,7 +3,7 @@ git-pull(1)
 
 NAME
 ----
-git-pull - Fetch from and merge with another repository or a local branch
+git-pull - Fetch from and integrate with another repository or a local branch
 
 
 SYNOPSIS
@@ -42,6 +42,8 @@ Assume the following history exists and the current branch is
          A---B---C master on origin
         /
     D---E---F---G master
+       ^
+       origin/master in your repository
 ------------
 
 Then "`git pull`" will fetch and replay the changes from the remote
@@ -51,7 +53,7 @@ result in a new commit along with the names of the two parent commits
 and a log message from the user describing the changes.
 
 ------------
-         A---B---C remotes/origin/master
+         A---B---C origin/master
         /         \
     D---E---F---G---H master
 ------------
@@ -59,8 +61,8 @@ and a log message from the user describing the changes.
 See linkgit:git-merge[1] for details, including how conflicts
 are presented and handled.
 
-In git 1.7.0 or later, to cancel a conflicting merge, use
-`git reset --merge`.  *Warning*: In older versions of git, running 'git pull'
+In Git 1.7.0 or later, to cancel a conflicting merge, use
+`git reset --merge`.  *Warning*: In older versions of Git, running 'git pull'
 with uncommitted changes is discouraged: while possible, it leaves you
 in a state that may be hard to back out of in the case of a conflict.
 
@@ -72,9 +74,6 @@ pulling or stash them away with linkgit:git-stash[1].
 OPTIONS
 -------
 
-Options meant for 'git pull' itself and the underlying 'git merge'
-must be given before the options meant for 'git fetch'.
-
 -q::
 --quiet::
        This is passed to both underlying git-fetch to squelch reporting of
@@ -89,7 +88,7 @@ must be given before the options meant for 'git fetch'.
        This option controls if new commits of all populated submodules should
        be fetched too (see linkgit:git-config[1] and linkgit:gitmodules[5]).
        That might be necessary to get the data needed for merging submodule
-       commits, a feature git learned in 1.7.3. Notice that the result of a
+       commits, a feature Git learned in 1.7.3. Notice that the result of a
        merge will not be checked out in the submodule, "git submodule update"
        has to be called afterwards to bring the work tree up to date with the
        merge result.
@@ -97,19 +96,26 @@ must be given before the options meant for 'git fetch'.
 Options related to merging
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-include::merge-options.txt[]
-
 :git-pull: 1
 
+include::merge-options.txt[]
+
 -r::
---rebase::
-       Rebase the current branch on top of the upstream branch after
-       fetching.  If there is a remote-tracking branch corresponding to
-       the upstream branch and the upstream branch was rebased since last
-       fetched, the rebase uses that information to avoid rebasing
-       non-local changes.
+--rebase[=false|true|preserve|interactive]::
+       When true, rebase the current branch on top of the upstream
+       branch after fetching. If there is a remote-tracking branch
+       corresponding to the upstream branch and the upstream branch
+       was rebased since last fetched, the rebase uses that information
+       to avoid rebasing non-local changes.
++
+When set to preserve, rebase with the `--preserve-merges` option passed
+to `git rebase` so that locally created merge commits will not be flattened.
++
+When false, merge the current branch into the upstream branch.
++
+When `interactive`, enable the interactive mode of rebase.
 +
-See `pull.rebase`, `branch.<name>.rebase` and `branch.autosetuprebase` in
+See `pull.rebase`, `branch.<name>.rebase` and `branch.autoSetupRebase` in
 linkgit:git-config[1] if you want to make `git pull` always use
 `--rebase` instead of merging.
 +
@@ -218,7 +224,7 @@ $ git merge origin/next
 ------------------------------------------------
 
 
-If you tried a pull which resulted in a complex conflicts and
+If you tried a pull which resulted in complex conflicts and
 would want to start over, you can recover with 'git reset'.
 
 
@@ -228,7 +234,7 @@ Using --recurse-submodules can only fetch new commits in already checked
 out submodules right now. When e.g. upstream added a new submodule in the
 just fetched commits of the superproject the submodule itself can not be
 fetched, making it impossible to check out that submodule later without
-having to do a fetch again. This is expected to be fixed in a future git
+having to do a fetch again. This is expected to be fixed in a future Git
 version.
 
 SEE ALSO