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)

changes in v3:

Change "fails if the local branch has diverged" to say "remote branch has diverged", from Junio's review.

I did not come up with a better idea for a word to use than "integrate" so left that alone.

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         | 93 +++++++++++++----------------
 Documentation/pull-fetch-param.adoc |  1 +
 2 files changed, 41 insertions(+), 53 deletions(-)

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

Range-diff vs v2:

 1:  4cc87ec354 = 1:  96b2673e04 doc: git-pull: move <repository> and <refspec> params
 2:  122774d4cc ! 2:  0ff00b4ff6 doc: git-pull: clarify options for integrating remote branch
     @@ Documentation/git-pull.adoc: SYNOPSIS
      +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.
     ++   fails if your local branch has diverged from the remote branch.
     ++   This is the default.
      +2. `git pull --rebase` runs `git rebase`
      +3. `git pull --no-rebase` runs `git merge`.
      +4. `git pull --squash` runs `git merge --squash`
 3:  323e81f2fd = 3:  2439c3d847 doc: git-pull: delete the example
 4:  999dfba156 = 4:  2236dac4e4 doc: git-pull: clarify how to exit a conflicted merge

gitgitgadget