doc: git-pull: move <repository> and <refspec> params

Git fork

From user feedback:

- it's confusing that we use both <branch> and <refspec> to refer to the
second argument
- one user is not clear about what `refs/heads/*:refs/remotes/origin/*`
is meant to be an example of ("is it like a path?")

The DESCRIPTION section is also doing a lot right now: it's trying to
describe both how the <repository> and <refspec> arguments work (which
is pretty complex, as seen in the DEFAULT BEHAVIOUR section)
as well as how `git pull` calls `git fetch` and merge/rebase/etc
depending on the arguments.

Handle this by moving the description of the <repository> and <refspec>
arguments to the OPTIONS section, so that we can focus on the
merge/rebase/etc behaviour in the DESCRIPTION section, and refer folks
to the later sections for details.

Use the term "upstream" instead of 'the "remote" and "merge"
configuration for the current branch' since users are more likely to
know what an "upstream" is.

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

authored by

Julia Evans and committed by

Junio C Hamano 4 months ago 85abbfc5 92c87bdc

+22 -11

2 changed files

expand all

unified split

Documentation

git-pull.adoc

pull-fetch-param.adoc

+21 -11

Documentation/git-pull.adoc

··· 27 27 will call either `git rebase` or `git merge` to reconcile diverging 28 28 branches. 29 29 30 - <repository> should be the name of a remote repository as 31 - passed to linkgit:git-fetch[1]. <refspec> can name an 32 - arbitrary remote ref (for example, the name of a tag) or even 33 - a collection of refs with corresponding remote-tracking branches 34 - (e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}), 35 - but usually it is the name of a branch in the remote repository. 36 - 37 - Default values for <repository> and <branch> are read from the 38 - "remote" and "merge" configuration for the current branch 39 - as set by linkgit:git-branch[1] `--track`. 40 - 41 30 Assume the following history exists and the current branch is 42 31 "`master`": 43 32 ··· 76 65 77 66 OPTIONS 78 67 ------- 68 + 69 + <repository>:: 70 + The "remote" repository to pull from. This can be either 71 + a URL (see the section <<URLS,GIT URLS>> below) or the name 72 + of a remote (see the section <<REMOTES,REMOTES>> below). 73 + + 74 + Defaults to the configured upstream for the current branch, or `origin`. 75 + See <<UPSTREAM-BRANCHES,UPSTREAM BRANCHES>> below for more on how to 76 + configure upstreams. 77 + 78 + <refspec>:: 79 + Which branch or other reference(s) to fetch and integrate into the 80 + current branch, for example `main` in `git pull origin main`. 81 + Defaults to the configured upstream for the current branch. 82 + + 83 + This can be a branch, tag, or other collection of reference(s). 84 + See <<fetch-refspec,<refspec>>> below under "Options related to fetching" 85 + for the full syntax, and <<DEFAULT-BEHAVIOUR,DEFAULT BEHAVIOUR>> below 86 + for how `git pull` uses this argument to determine which remote branch 87 + to integrate. 79 88 80 89 -q:: 81 90 --quiet:: ··· 145 154 146 155 include::merge-strategies.adoc[] 147 156 157 + [[DEFAULT-BEHAVIOUR]] 148 158 DEFAULT BEHAVIOUR 149 159 ----------------- 150 160

Documentation/pull-fetch-param.adoc

··· 11 11 (See linkgit:git-config[1]). 12 12 endif::git-pull[] 13 13 14 + [[fetch-refspec]] 14 15 <refspec>:: 15 16 Specifies which refs to fetch and which local refs to update. 16 17 When no <refspec>s appear on the command line, the refs to fetch