From 85abbfc59b070816871ff64bba3eba94e749ce08 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Wed, 15 Oct 2025 13:13:28 +0000 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 Signed-off-by: Junio C Hamano --- 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 48e924a10a..a3d248dd1d 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 d79d2f6065..bb2cf6a462 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 59b28f928b2b3b91033ee4e9cbe0cf51a781e55b Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Wed, 15 Oct 2025 13:13:29 +0000 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 Signed-off-by: Junio C Hamano --- Documentation/git-pull.adoc | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc index a3d248dd1d..0686a9d666 100644 --- a/Documentation/git-pull.adoc +++ b/Documentation/git-pull.adoc @@ -15,17 +15,26 @@ 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`). +Integrate changes from a remote repository into the current branch. -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. +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 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` + +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 d8942ac494fb08b5b99a3eb6fb6a2853a0232d21 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Wed, 15 Oct 2025 13:13:30 +0000 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 Signed-off-by: Junio C Hamano --- Documentation/git-pull.adoc | 26 -------------------------- 1 file changed, 26 deletions(-) diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc index 0686a9d666..273172aa80 100644 --- a/Documentation/git-pull.adoc +++ b/Documentation/git-pull.adoc @@ -36,32 +36,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 e9d221b0b70869fa770e95acf143149c0b8705f6 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Wed, 15 Oct 2025 13:13:31 +0000 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 Signed-off-by: Junio C Hamano --- 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 273172aa80..cd3bbc90e3 100644 --- a/Documentation/git-pull.adoc +++ b/Documentation/git-pull.adoc @@ -36,15 +36,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 -------