From: "Julia Evans via GitGitGadget" <gitgitgadget@gmail•com>
To: git@vger•kernel.org
Cc: Julia Evans <julia@jvns•ca>, Julia Evans <julia@jvns•ca>
Subject: [PATCH 1/4] doc: git-pull: move <repository> and <refspec> params
Date: Tue, 23 Sep 2025 19:44:59 +0000 [thread overview]
Message-ID: <f69d2e6fabbace9ae76cb3822b063a3f19622138.1758656702.git.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.1976.git.1758656702.gitgitgadget@gmail.com>
From: Julia Evans <julia@jvns•ca>
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>
---
Documentation/git-pull.adoc | 29 ++++++++++++++++++-----------
1 file changed, 18 insertions(+), 11 deletions(-)
diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc
index 48e924a10a..50af7fde81 100644
--- a/Documentation/git-pull.adoc
+++ b/Documentation/git-pull.adoc
@@ -27,17 +27,6 @@ and then depending on configuration options or command line flags,
will call either `git rebase` or `git merge` to reconcile diverging
branches.
-<repository> should be the name of a remote repository as
-passed to linkgit:git-fetch[1]. <refspec> can name an
-arbitrary remote ref (for example, the name of a tag) or even
-a collection of refs with corresponding remote-tracking branches
-(e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}),
-but usually it is the name of a branch in the remote repository.
-
-Default values for <repository> and <branch> are read from the
-"remote" and "merge" configuration for the current branch
-as set by linkgit:git-branch[1] `--track`.
-
Assume the following history exists and the current branch is
"`master`":
@@ -77,6 +66,24 @@ pulling or stash them away with linkgit:git-stash[1].
OPTIONS
-------
+<repository>::
+ The "remote" repository to pull from. This can be either
+ a URL (see the section <<URLS,GIT URLS>> below) or the name
+ 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.
+
+<refspec>::
+ Which branch or other reference(s) to fetch and integrate into the
+ current branch, for example `main` in `git pull origin main`.
+ 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.
+
-q::
--quiet::
This is passed to both underlying git-fetch to squelch reporting of
--
gitgitgadget
next prev parent reply other threads:[~2025-09-23 19:45 UTC|newest]
Thread overview: 32+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-09-23 19:44 [PATCH 0/4] doc: git-pull: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-09-23 19:44 ` Julia Evans via GitGitGadget [this message]
2025-09-24 20:17 ` [PATCH 1/4] doc: git-pull: move <repository> and <refspec> params D. Ben Knoble
2025-10-07 21:20 ` Julia Evans
2025-09-23 19:45 ` [PATCH 2/4] doc: git-pull: clarify options for integrating remote branch Julia Evans via GitGitGadget
2025-09-24 20:23 ` D. Ben Knoble
2025-09-24 20:54 ` Julia Evans
2025-09-24 22:38 ` Chris Torek
2025-10-06 21:16 ` Julia Evans
2025-09-23 19:45 ` [PATCH 3/4] doc: git-pull: delete the example Julia Evans via GitGitGadget
2025-09-23 19:45 ` [PATCH 4/4] doc: git-pull: clarify how to exit a conflicted merge Julia Evans via GitGitGadget
2025-09-24 17:21 ` Julia Evans
2025-09-24 20:29 ` D. Ben Knoble
2025-10-07 21:01 ` Julia Evans
2025-10-10 0:45 ` Ben Knoble
2025-09-24 19:56 ` [PATCH 0/4] doc: git-pull: clarify DESCRIPTION section D. Ben Knoble
2025-10-08 19:25 ` [PATCH v2 " Julia Evans via GitGitGadget
2025-10-08 19:25 ` [PATCH v2 1/4] doc: git-pull: move <repository> and <refspec> params Julia Evans via GitGitGadget
2025-10-08 19:25 ` [PATCH v2 2/4] doc: git-pull: clarify options for integrating remote branch Julia Evans via GitGitGadget
2025-10-08 21:33 ` Junio C Hamano
2025-10-09 21:31 ` Julia Evans
2025-10-09 22:20 ` Kristoffer Haugsbakk
2025-10-09 22:41 ` Junio C Hamano
2025-10-08 19:25 ` [PATCH v2 3/4] doc: git-pull: delete the example Julia Evans via GitGitGadget
2025-10-08 19:25 ` [PATCH v2 4/4] doc: git-pull: clarify how to exit a conflicted merge Julia Evans via GitGitGadget
2025-10-15 13:13 ` [PATCH v3 0/4] doc: git-pull: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-10-15 13:13 ` [PATCH v3 1/4] doc: git-pull: move <repository> and <refspec> params Julia Evans via GitGitGadget
2025-10-15 13:13 ` [PATCH v3 2/4] doc: git-pull: clarify options for integrating remote branch Julia Evans via GitGitGadget
2025-10-15 13:13 ` [PATCH v3 3/4] doc: git-pull: delete the example Julia Evans via GitGitGadget
2025-10-15 13:13 ` [PATCH v3 4/4] doc: git-pull: clarify how to exit a conflicted merge Julia Evans via GitGitGadget
2025-10-15 16:56 ` [PATCH v3 0/4] doc: git-pull: clarify DESCRIPTION section Ben Knoble
2025-10-15 20:36 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=f69d2e6fabbace9ae76cb3822b063a3f19622138.1758656702.git.gitgitgadget@gmail.com \
--to=gitgitgadget@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=julia@jvns$(echo .)ca \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox