From 4cc87ec354f7b9ec599d70046f3263363546bebe Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Tue, 23 Sep 2025 14:18:22 -0400 Subject: [PATCH 1/4] doc: git-pull: move and params From user feedback: - it's confusing that we use both and 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 and 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 and 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 --- Documentation/git-pull.adoc | 32 +++++++++++++++++++---------- Documentation/pull-fetch-param.adoc | 1 + 2 files changed, 22 insertions(+), 11 deletions(-) diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc index 48e924a10a40c0..a3d248dd1d0c65 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. - should be the name of a remote repository as -passed to linkgit:git-fetch[1]. 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 and 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,26 @@ pulling or stash them away with linkgit:git-stash[1]. OPTIONS ------- +:: + The "remote" repository to pull from. This can be either + a URL (see the section <> below) or the name + of a remote (see the section <> below). ++ +Defaults to the configured upstream for the current branch, or `origin`. +See <> below for more on how to +configure upstreams. + +:: + 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 <>> below under "Options related to fetching" +for the full syntax, and <> 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 @@ -145,6 +154,7 @@ include::urls-remotes.adoc[] include::merge-strategies.adoc[] +[[DEFAULT-BEHAVIOUR]] DEFAULT BEHAVIOUR ----------------- diff --git a/Documentation/pull-fetch-param.adoc b/Documentation/pull-fetch-param.adoc index d79d2f6065bcd4..bb2cf6a4629e92 100644 --- a/Documentation/pull-fetch-param.adoc +++ b/Documentation/pull-fetch-param.adoc @@ -11,6 +11,7 @@ ifndef::git-pull[] (See linkgit:git-config[1]). endif::git-pull[] +[[fetch-refspec]] :: Specifies which refs to fetch and which local refs to update. When no s appear on the command line, the refs to fetch From 122774d4cc8fa4e9184a0f82e9b6e562363ea433 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Tue, 23 Sep 2025 14:46:10 -0400 Subject: [PATCH 2/4] doc: git-pull: clarify options for integrating remote branch From user feedback: - One user is confused about the current default ("I was convinced that the git default was still to merge on pull") - One user is confused about why "git fetch" isn't mentioned earlier - One user says they always forget what the arguments to `git pull` are and that it's not immediately obvious that `--no-rebase` means "merge" - One user wants `--ff-only` to be mentioned Resolve this by listing the options for integrating the the remote branch. This should help users figure out at a glance which one they want to do, and make it clearer that --ff-only is the default. Signed-off-by: Julia Evans --- Documentation/git-pull.adoc | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc index a3d248dd1d0c65..6e9fa149675174 100644 --- a/Documentation/git-pull.adoc +++ b/Documentation/git-pull.adoc @@ -15,17 +15,25 @@ SYNOPSIS DESCRIPTION ----------- -Incorporates changes from a remote repository into the current branch. -If the current branch is behind the remote, then by default it will -fast-forward the current branch to match the remote. If the current -branch and the remote have diverged, the user needs to specify how to -reconcile the divergent branches with `--rebase` or `--no-rebase` (or -the corresponding configuration option in `pull.rebase`). - -More precisely, `git pull` runs `git fetch` with the given parameters -and then depending on configuration options or command line flags, -will call either `git rebase` or `git merge` to reconcile diverging -branches. +Integrate changes from a remote repository into the current 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 <> +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. +2. `git pull --rebase` runs `git rebase` +3. `git pull --no-rebase` runs `git merge`. +4. `git pull --squash` runs `git merge --squash` + +You can also set the configuration options `pull.rebase`, `pull.squash`, +or `pull.ff` with your preferred behaviour. Assume the following history exists and the current branch is "`master`": From 323e81f2fd4efadf21bf5a77fe164d09e12665b6 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Tue, 23 Sep 2025 14:55:51 -0400 Subject: [PATCH 3/4] doc: git-pull: delete the example From user feedback: this example is confusing because it implies that `git pull` will run `git merge` by default, but the default is `--ff-only`. We could instead show an example of a fast-forward merge, but that may not add a lot since fast-forward merges are relatively simple. This lets us keep the description short. Signed-off-by: Julia Evans --- Documentation/git-pull.adoc | 26 -------------------------- 1 file changed, 26 deletions(-) diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc index 6e9fa149675174..dc93e5e6d7bc3a 100644 --- a/Documentation/git-pull.adoc +++ b/Documentation/git-pull.adoc @@ -35,32 +35,6 @@ 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. -Assume the following history exists and the current branch is -"`master`": - ------------- - A---B---C master on origin - / - D---E---F---G master - ^ - origin/master in your repository ------------- - -Then "`git pull`" will fetch and replay the changes from the remote -`master` branch since it diverged from the local `master` (i.e., `E`) -until its current commit (`C`) on top of `master` and record the -result in a new commit along with the names of the two parent commits -and a log message from the user describing the changes. - ------------- - A---B---C origin/master - / \ - D---E---F---G---H master ------------- - -See linkgit:git-merge[1] for details, including how conflicts -are presented and handled. - In Git 1.7.0 or later, to cancel a conflicting merge, use `git reset --merge`. *Warning*: In older versions of Git, running 'git pull' with uncommitted changes is discouraged: while possible, it leaves you From 999dfba15610ce5d6ddc19f4512de64181184920 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Tue, 23 Sep 2025 14:59:27 -0400 Subject: [PATCH 4/4] doc: git-pull: clarify how to exit a conflicted merge From user feedback: - One user is confused about why `git reset --merge` (why not just `git reset`?). Handle this by mentioning `git merge --abort` and `git reset --abort` instead, which have a more obvious meaning. - 2 users want to know what "In older versions of Git" means exactly (in versions older than 1.7.0). Handle this by removing the warning since it was added 15 years ago (in 3f8fc184c0e2c) Signed-off-by: Julia Evans --- Documentation/git-pull.adoc | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc index dc93e5e6d7bc3a..8d286425d623dc 100644 --- a/Documentation/git-pull.adoc +++ b/Documentation/git-pull.adoc @@ -35,15 +35,9 @@ 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. -In Git 1.7.0 or later, to cancel a conflicting merge, use -`git reset --merge`. *Warning*: In older versions of Git, running 'git pull' -with uncommitted changes is discouraged: while possible, it leaves you -in a state that may be hard to back out of in the case of a conflict. - -If any of the remote changes overlap with local uncommitted changes, -the merge will be automatically canceled and the work tree untouched. -It is generally best to get any local changes in working order before -pulling or stash them away with linkgit:git-stash[1]. +If there's a merge conflict during the merge or rebase that you don't +want to handle, you can safely abort it with `git merge --abort` or `git +--rebase abort`. OPTIONS -------