[PATCH v2 0/4] doc: git-pull: clarify DESCRIPTION section

I got feedback from 15 Git users on the current git pull man page, using this tool: https://text-feedback.wizardzines.com/git-pull.

My goals here are to be clear about the relationship between git pull and fetch/merge/rebase etc, make sure users know the current default for git pull (--ff-only) since some folks still remember the old default, and to help users quickly figure out what command they need to run to merge/rebase/squash/etc.

I've taken a pretty aggressive approach because I think it's possible to have a pretty short and focused DESCRIPTION section here while keeping the most important info. Open to hearing that I've removed too much.

This references the UPSTREAM BRANCHES section from https://lore.kernel.org/git/0ec629d4037bf5d1ccc248ca1bbd87ccc08119a3.1757703309.git.gitgitgadget@gmail.com/ , so if that isn't merged I'll need to revisit the approach here.

changes in v2:

 * Add "(excluding merge options)" to clarify which options are passed to
   git fetch (from Chris's review)
 * Say that git pull will by default merge the upstream branch. (from
   Chris's review)
 * Add some links to the UPSTREAM BRANCHES section, and to the <refspec>
   section in git fetch, to make it easier to navigate in the HTML version
   of the docs at least. The situation where we repeat the <repository> part
   in git fetch is weird but I don't have a better idea for how to handle it
   right now. The UPSTREAM BRANCHES links are currently failing the
   documentation tests, but should pass once the patch series that adds that
   is merged. (from Ben's review)

Julia Evans (4):
  doc: git-pull: move <repository> and <refspec> params
  doc: git-pull: clarify options for integrating remote branch
  doc: git-pull: delete the example
  doc: git-pull: clarify how to exit a conflicted merge

 Documentation/git-pull.adoc         | 92 ++++++++++++-----------------
 Documentation/pull-fetch-param.adoc |  1 +
 2 files changed, 40 insertions(+), 53 deletions(-)

base-commit: ca2559c1d630eb4f04cdee2328aaf1c768907a9e
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1976%2Fjvns%2Fclarify-pull-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1976/jvns/clarify-pull-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1976

Range-diff vs v1:

 1:  f69d2e6fab ! 1:  4cc87ec354 doc: git-pull: move <repository> and <refspec> params
     @@ Documentation/git-pull.adoc: pulling or stash them away with linkgit:git-stash[1
      +	of a remote (see the section <<REMOTES,REMOTES>> below).
      ++
      +Defaults to the configured upstream for the current branch, or `origin`.
     -+See UPSTREAM BRANCHES below for more on how to configure upstreams.
     ++See <<UPSTREAM-BRANCHES,UPSTREAM BRANCHES>> below for more on how to
     ++configure upstreams.
      +
      +<refspec>::
      +	Which branch or other reference(s) to fetch and integrate into the
     @@ Documentation/git-pull.adoc: pulling or stash them away with linkgit:git-stash[1
      +	Defaults to the configured upstream for the current branch.
      ++
      +This can be a branch, tag, or other collection of reference(s).
     -+See <refspec> below under "Options related to fetching" for the full syntax,
     -+and DEFAULT BEHAVIOUR below for how `git pull` uses this argument to
     -+determine which remote branch to integrate.
     ++See <<fetch-refspec,<refspec>>> below under "Options related to fetching"
     ++for the full syntax, and <<DEFAULT-BEHAVIOUR,DEFAULT BEHAVIOUR>> below
     ++for how `git pull` uses this argument to determine which remote branch
     ++to integrate.
      +
       -q::
       --quiet::
       	This is passed to both underlying git-fetch to squelch reporting of
     +@@ Documentation/git-pull.adoc: include::urls-remotes.adoc[]
     + 
     + include::merge-strategies.adoc[]
     + 
     ++[[DEFAULT-BEHAVIOUR]]
     + DEFAULT BEHAVIOUR
     + -----------------
     + 
     +
     + ## Documentation/pull-fetch-param.adoc ##
     +@@ Documentation/pull-fetch-param.adoc: ifndef::git-pull[]
     + 	(See linkgit:git-config[1]).
     + endif::git-pull[]
     + 
     ++[[fetch-refspec]]
     + <refspec>::
     + 	Specifies which refs to fetch and which local refs to update.
     + 	When no <refspec>s appear on the command line, the refs to fetch
 2:  ffbb9d7c6a ! 2:  122774d4cc doc: git-pull: clarify options for integrating remote branch
     @@ Documentation/git-pull.adoc: SYNOPSIS
      -branches.
      +Integrate changes from a remote repository into the current branch.
      +
     -+First, `git pull` runs `git fetch` with the same arguments to fetch
     -+remote branch(es). Then it integrates the remote branch into the current
     -+branch. There are 4 main options for integrating the remote branch:
     ++First, `git pull` runs `git fetch` with the same arguments
     ++(excluding merge options) to fetch remote branch(es).
     ++Then it decides which remote branch to integrate: if you run `git pull`
     ++with no arguments this defaults to the <<UPSTREAM-BRANCHES,upstream>>
     ++for the current branch.
     ++Then it integrates that branch into the current branch.
     ++
     ++There are 4 main options for integrating the remote branch:
      +
      +1. `git pull --ff-only` will only do "fast-forward" updates: it
      +   fails if the remote branch has diverged. This is the default.
 3:  76dc2c19fb ! 3:  323e81f2fd doc: git-pull: delete the example
     @@ Commit message
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
       ## Documentation/git-pull.adoc ##
     -@@ Documentation/git-pull.adoc: branch. There are 4 main options for integrating the remote branch:
     +@@ Documentation/git-pull.adoc: There are 4 main options for integrating the remote branch:
       You can also set the configuration options `pull.rebase`, `pull.squash`,
       or `pull.ff` with your preferred behaviour.
       
 4:  c7f09c2bd3 ! 4:  999dfba156 doc: git-pull: clarify how to exit a conflicted merge
     @@ Commit message
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
       ## Documentation/git-pull.adoc ##
     -@@ Documentation/git-pull.adoc: branch. There are 4 main options for integrating the remote branch:
     +@@ Documentation/git-pull.adoc: There are 4 main options for integrating the remote branch:
       You can also set the configuration options `pull.rebase`, `pull.squash`,
       or `pull.ff` with your preferred behaviour.