@matheusbsbs / matheus-bagliano / commits / 85abbfc59b

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

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>

Julia Evans committed Oct 15, 2025 at 13:13 UTC 85abbfc59b070816871ff64bba3eba94e749ce08

2 files changed +22 -11

Documentation/git-pull.adoc

+21 -11

@@ -27,17 +27,6 @@ and then depending on configuration options or command line flags,

27 will call either `git rebase` or `git merge` to reconcile diverging

28 branches.

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 -

30 Assume the following history exists and the current branch is

31 "`master`":

@@ -77,6 +66,26 @@ pulling or stash them away with linkgit:git-stash[1].

66 OPTIONS

67 -------

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.

88 +

89 -q::

90 --quiet::

91 This is passed to both underlying git-fetch to squelch reporting of

@@ -145,6 +154,7 @@ include::urls-remotes.adoc[]

154

155 include::merge-strategies.adoc[]

156

157 +[[DEFAULT-BEHAVIOUR]]

158 DEFAULT BEHAVIOUR

159 -----------------

160

Documentation/pull-fetch-param.adoc

@@ -11,6 +11,7 @@ ifndef::git-pull[]

11 (See linkgit:git-config[1]).

12 endif::git-pull[]

14 +[[fetch-refspec]]

15 <refspec>::

16 Specifies which refs to fetch and which local refs to update.

17 When no <refspec>s appear on the command line, the refs to fetch