{"thread":{"id":"64194","subject":"[PATCH 0/4] doc: git-pull: clarify DESCRIPTION section","startedAt":"2025-09-23T19:45:06Z","lastAt":"2025-10-15T20:36:22Z","messageCount":32,"participants":["Julia Evans via GitGitGadget","Julia Evans","D. Ben Knoble","Chris Torek","Junio C Hamano","Kristoffer Haugsbakk","Ben Knoble"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"527130","messageId":"pull.1976.git.1758656702.gitgitgadget@gmail.com","threadId":"64194","inReplyTo":null,"subject":"[PATCH 0/4] doc: git-pull: clarify DESCRIPTION section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-23T19:44:58Z","receivedAt":"2025-09-23T19:45:06Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"I got feedback from 15 Git users on the current git pull man page, using\nthis tool: https://text-feedback.wizardzines.com/git-pull.\n\nMy goals here are to be clear about the relationship between git pull and\nfetch/merge/rebase etc, make sure users know the current default for git\npull (--ff-only) since some folks still remember the old default, and to\nhelp users quickly figure out what command they need to run to\nmerge/rebase/squash/etc.\n\nI've taken a pretty aggressive approach because I think it's possible to\nhave a pretty short and focused DESCRIPTION section here while keeping the\nmost important info. Open to hearing that I've removed too much.\n\nThis references the UPSTREAM BRANCHES section from\nhttps://lore.kernel.org/git/0ec629d4037bf5d1ccc248ca1bbd87ccc08119a3.1757703309.git.gitgitgadget@gmail.com/\n, so if that isn't merged I'll need to revisit the approach here.\n\nJulia Evans (4):\n doc: git-pull: move and params\n doc: git-pull: clarify options for integrating remote branch\n doc: git-pull: delete the example\n doc: git-pull: clarify how to exit a conflicted merge\n\n Documentation/git-pull.adoc | 86 ++++++++++++++-----------------------\n 1 file changed, 32 insertions(+), 54 deletions(-)\n\n\nbase-commit: ca2559c1d630eb4f04cdee2328aaf1c768907a9e\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1976%2Fjvns%2Fclarify-pull-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1976/jvns/clarify-pull-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1976\n-- \ngitgitgadget\n"},{"id":"527131","messageId":"f69d2e6fabbace9ae76cb3822b063a3f19622138.1758656702.git.gitgitgadget@gmail.com","threadId":"64194","inReplyTo":"pull.1976.git.1758656702.gitgitgadget@gmail.com","subject":"[PATCH 1/4] doc: git-pull: move and params","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-23T19:44:59Z","receivedAt":"2025-09-23T19:45:08Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nFrom user feedback:\n\n- it's confusing that we use both and to refer to the\n second argument\n- one user is not clear about what `refs/heads/*:refs/remotes/origin/*`\n is meant to be an example of (\"is it like a path?\")\n\nThe DESCRIPTION section is also doing a lot right now: it's trying to\ndescribe both how the and arguments work (which\nis pretty complex, as seen in the DEFAULT BEHAVIOUR section)\nas well as how `git pull` calls `git fetch` and merge/rebase/etc\ndepending on the arguments.\n\nHandle this by moving the description of the and \narguments to the OPTIONS section, so that we can focus on the\nmerge/rebase/etc behaviour in the DESCRIPTION section, and refer folks\nto the later sections for details.\n\nUse the term \"upstream\" instead of 'the \"remote\" and \"merge\"\nconfiguration for the current branch' since users are more likely to\nknow what an \"upstream\" is.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-pull.adoc | 29 ++++++++++++++++++-----------\n 1 file changed, 18 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex 48e924a10a..50af7fde81 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -27,17 +27,6 @@ and then depending on configuration options or command line flags,\n will call either `git rebase` or `git merge` to reconcile diverging\n branches.\n \n- should be the name of a remote repository as\n-passed to linkgit:git-fetch[1]. can name an\n-arbitrary remote ref (for example, the name of a tag) or even\n-a collection of refs with corresponding remote-tracking branches\n-(e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}),\n-but usually it is the name of a branch in the remote repository.\n-\n-Default values for and are read from the\n-\"remote\" and \"merge\" configuration for the current branch\n-as set by linkgit:git-branch[1] `--track`.\n-\n Assume the following history exists and the current branch is\n \"`master`\":\n \n@@ -77,6 +66,24 @@ pulling or stash them away with linkgit:git-stash[1].\n OPTIONS\n -------\n \n+::\n+\tThe \"remote\" repository to pull from. This can be either\n+\ta URL (see the section <> below) or the name\n+\tof a remote (see the section <> below).\n++\n+Defaults to the configured upstream for the current branch, or `origin`.\n+See UPSTREAM BRANCHES below for more on how to configure upstreams.\n+\n+::\n+\tWhich branch or other reference(s) to fetch and integrate into the\n+\tcurrent branch, for example `main` in `git pull origin main`.\n+\tDefaults to the configured upstream for the current branch.\n++\n+This can be a branch, tag, or other collection of reference(s).\n+See below under \"Options related to fetching\" for the full syntax,\n+and DEFAULT BEHAVIOUR below for how `git pull` uses this argument to\n+determine which remote branch to integrate.\n+\n -q::\n --quiet::\n \tThis is passed to both underlying git-fetch to squelch reporting of\n-- \ngitgitgadget\n\n"},{"id":"527132","messageId":"ffbb9d7c6aff77f9a1caed86a20bcc6b9afe66e7.1758656702.git.gitgitgadget@gmail.com","threadId":"64194","inReplyTo":"pull.1976.git.1758656702.gitgitgadget@gmail.com","subject":"[PATCH 2/4] doc: git-pull: clarify options for integrating remote branch","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-23T19:45:00Z","receivedAt":"2025-09-23T19:45:11Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nFrom user feedback:\n\n- One user is confused about the current default (\"I was convinced that\n the git default was still to merge on pull\")\n- One user is confused about why \"git fetch\" isn't mentioned earlier\n- One user says they always forget what the arguments to `git pull` are\n and that it's not immediately obvious that `--no-rebase` means \"merge\"\n- One user wants `--ff-only` to be mentioned\n\nResolve this by listing the options for integrating the the remote\nbranch. This should help users figure out at a glance which one they\nwant to do, and make it clearer that --ff-only is the default.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-pull.adoc | 25 ++++++++++++++-----------\n 1 file changed, 14 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex 50af7fde81..61d18fef36 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -15,17 +15,20 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-Incorporates changes from a remote repository into the current branch.\n-If the current branch is behind the remote, then by default it will\n-fast-forward the current branch to match the remote. If the current\n-branch and the remote have diverged, the user needs to specify how to\n-reconcile the divergent branches with `--rebase` or `--no-rebase` (or\n-the corresponding configuration option in `pull.rebase`).\n-\n-More precisely, `git pull` runs `git fetch` with the given parameters\n-and then depending on configuration options or command line flags,\n-will call either `git rebase` or `git merge` to reconcile diverging\n-branches.\n+Integrate changes from a remote repository into the current branch.\n+\n+First, `git pull` runs `git fetch` with the same arguments to fetch\n+remote branch(es). Then it integrates the remote branch into the current\n+branch. There are 4 main options for integrating the remote branch:\n+\n+1. `git pull --ff-only` will only do \"fast-forward\" updates: it\n+ fails if the remote branch has diverged. This is the default.\n+2. `git pull --rebase` runs `git rebase`\n+3. `git pull --no-rebase` runs `git merge`.\n+4. `git pull --squash` runs `git merge --squash`\n+\n+You can also set the configuration options `pull.rebase`, `pull.squash`,\n+or `pull.ff` with your preferred behaviour.\n \n Assume the following history exists and the current branch is\n \"`master`\":\n-- \ngitgitgadget\n\n"},{"id":"527133","messageId":"76dc2c19fb2b642c5842349a8c1ba504180c9203.1758656702.git.gitgitgadget@gmail.com","threadId":"64194","inReplyTo":"pull.1976.git.1758656702.gitgitgadget@gmail.com","subject":"[PATCH 3/4] doc: git-pull: delete the example","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-23T19:45:01Z","receivedAt":"2025-09-23T19:45:12Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nFrom user feedback: this example is confusing because it implies that\n`git pull` will run `git merge` by default, but the default is\n`--ff-only`.\n\nWe could instead show an example of a fast-forward merge, but that may\nnot add a lot since fast-forward merges are relatively simple. This lets\nus keep the description short.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-pull.adoc | 26 --------------------------\n 1 file changed, 26 deletions(-)\n\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex 61d18fef36..91903b0a94 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -30,32 +30,6 @@ branch. There are 4 main options for integrating the remote branch:\n You can also set the configuration options `pull.rebase`, `pull.squash`,\n or `pull.ff` with your preferred behaviour.\n \n-Assume the following history exists and the current branch is\n-\"`master`\":\n-\n-------------\n-\t A---B---C master on origin\n-\t /\n- D---E---F---G master\n-\t^\n-\torigin/master in your repository\n-------------\n-\n-Then \"`git pull`\" will fetch and replay the changes from the remote\n-`master` branch since it diverged from the local `master` (i.e., `E`)\n-until its current commit (`C`) on top of `master` and record the\n-result in a new commit along with the names of the two parent commits\n-and a log message from the user describing the changes.\n-\n-------------\n-\t A---B---C origin/master\n-\t / \\\n- D---E---F---G---H master\n-------------\n-\n-See linkgit:git-merge[1] for details, including how conflicts\n-are presented and handled.\n-\n In Git 1.7.0 or later, to cancel a conflicting merge, use\n `git reset --merge`. *Warning*: In older versions of Git, running 'git pull'\n with uncommitted changes is discouraged: while possible, it leaves you\n-- \ngitgitgadget\n\n"},{"id":"527134","messageId":"c7f09c2bd32baf9e1dda355656bba811484e90a0.1758656702.git.gitgitgadget@gmail.com","threadId":"64194","inReplyTo":"pull.1976.git.1758656702.gitgitgadget@gmail.com","subject":"[PATCH 4/4] doc: git-pull: clarify how to exit a conflicted merge","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-09-23T19:45:02Z","receivedAt":"2025-09-23T19:45:13Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nFrom user feedback:\n\n- One user is confused about why `git reset --merge`\n (why not just `git reset`?). Handle this by mentioning\n `git merge --abort` and `git reset --abort` instead, which have a\n more obvious meaning.\n- 2 users want to know what \"In older versions of Git\" means exactly\n (in versions older than 1.7.0). Handle this by removing the warning\n since it was added 15 years ago (in 3f8fc184c0e2c)\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-pull.adoc | 12 +++---------\n 1 file changed, 3 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex 91903b0a94..eec05ab6c7 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -30,15 +30,9 @@ branch. There are 4 main options for integrating the remote branch:\n You can also set the configuration options `pull.rebase`, `pull.squash`,\n or `pull.ff` with your preferred behaviour.\n \n-In Git 1.7.0 or later, to cancel a conflicting merge, use\n-`git reset --merge`. *Warning*: In older versions of Git, running 'git pull'\n-with uncommitted changes is discouraged: while possible, it leaves you\n-in a state that may be hard to back out of in the case of a conflict.\n-\n-If any of the remote changes overlap with local uncommitted changes,\n-the merge will be automatically canceled and the work tree untouched.\n-It is generally best to get any local changes in working order before\n-pulling or stash them away with linkgit:git-stash[1].\n+If there's a merge conflict during the merge or rebase that you don't\n+want to handle, you can safely abort it with `git merge --abort` or `git\n+--rebase abort`.\n \n OPTIONS\n -------\n-- \ngitgitgadget\n"},{"id":"527237","messageId":"1928a79e-c0e1-4510-8717-89053b54ff48@app.fastmail.com","threadId":"64194","inReplyTo":"c7f09c2bd32baf9e1dda355656bba811484e90a0.1758656702.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 4/4] doc: git-pull: clarify how to exit a conflicted merge","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-09-24T17:21:30Z","receivedAt":"2025-09-24T17:21:52Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"On Tue, Sep 23, 2025, at 3:45 PM, Julia Evans via GitGitGadget wrote:\n> From: Julia Evans \n>\n> From user feedback:\n>\n> - One user is confused about why `git reset --merge`\n> (why not just `git reset`?). Handle this by mentioning\n> `git merge --abort` and `git reset --abort` instead, which have a\n> more obvious meaning.\n> - 2 users want to know what \"In older versions of Git\" means exactly\n> (in versions older than 1.7.0). Handle this by removing the warning\n> since it was added 15 years ago (in 3f8fc184c0e2c)\n>\n> Signed-off-by: Julia Evans \n> ---\n> Documentation/git-pull.adoc | 12 +++---------\n> 1 file changed, 3 insertions(+), 9 deletions(-)\n>\n> diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\n> index 91903b0a94..eec05ab6c7 100644\n> --- a/Documentation/git-pull.adoc\n> +++ b/Documentation/git-pull.adoc\n> @@ -30,15 +30,9 @@ branch. There are 4 main options for integrating the \n> remote branch:\n> You can also set the configuration options `pull.rebase`, \n> `pull.squash`,\n> or `pull.ff` with your preferred behaviour.\n> \n> -In Git 1.7.0 or later, to cancel a conflicting merge, use\n> -`git reset --merge`. *Warning*: In older versions of Git, running 'git pull'\n> -with uncommitted changes is discouraged: while possible, it leaves you\n> -in a state that may be hard to back out of in the case of a conflict.\n> -\n> -If any of the remote changes overlap with local uncommitted changes,\n> -the merge will be automatically canceled and the work tree untouched.\n> -It is generally best to get any local changes in working order before\n> -pulling or stash them away with linkgit:git-stash[1].\n\nAfter sending this I thought to read the `git merge` man page, which has\nthis warning:\n\n> WARNING: Running `git merge` with non-trivial uncommitted changes is\ndiscouraged: while possible, it may leave you in a state that is hard to\nback out of in the case of a conflict.\n\nI think I was probably too hasty in removing the warning entirely, since I\nmainly use `git pull --rebase` and I hadn't fully thought through how\n`git merge` has a different approach to uncommitted changes than \n`git rebase`.\n\nI think a warning similar to that one would make sense, since any warning\nthat applies to `git merge` should also apply to `git pull`.\n\n> +If there's a merge conflict during the merge or rebase that you don't\n> +want to handle, you can safely abort it with `git merge --abort` or `git\n> +--rebase abort`.\n\nAlso I noticed a typo in `git --rebase abort` :)\n"},{"id":"527252","messageId":"CALnO6CBh_dcbZuSEebG28eQ+N1KfxzEuOp9uxsWEjBQ3Ci1ZYA@mail.gmail.com","threadId":"64194","inReplyTo":"pull.1976.git.1758656702.gitgitgadget@gmail.com","subject":"Re: [PATCH 0/4] doc: git-pull: clarify DESCRIPTION section","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-09-24T19:56:36Z","receivedAt":"2025-09-24T19:56:50Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Tue, Sep 23, 2025 at 3:45 PM Julia Evans via GitGitGadget\n wrote:\n>\n> I got feedback from 15 Git users on the current git pull man page, using\n> this tool: https://text-feedback.wizardzines.com/git-pull.\n>\n> My goals here are to be clear about the relationship between git pull and\n> fetch/merge/rebase etc, make sure users know the current default for git\n> pull (--ff-only) since some folks still remember the old default, and to\n> help users quickly figure out what command they need to run to\n> merge/rebase/squash/etc.\n\nHuh! I thought pull would merge divergent histories by default, and\neven now it's hard to extract that info from the manual (the first\nparagraph actually mentions reconciliation via --rebase/--no-rebase,\nbut I thought --no-rebase was still the default). TIL, thanks!\n\n> I've taken a pretty aggressive approach because I think it's possible to\n> have a pretty short and focused DESCRIPTION section here while keeping the\n> most important info. Open to hearing that I've removed too much.\n>\n> This references the UPSTREAM BRANCHES section from\n> https://lore.kernel.org/git/0ec629d4037bf5d1ccc248ca1bbd87ccc08119a3.1757703309.git.gitgitgadget@gmail.com/\n> , so if that isn't merged I'll need to revisit the approach here.\n\nA common way to handle this is to build your topic on top of the topic\nyou depend on, and then mention that in your cover letter. I'm not\nsure how GitGitGadget handles that, though, since with format-patch\nyou could then specify to send patches only from\n... So I think this is probably ok?\n\n-- \nD. Ben Knoble\n"},{"id":"527255","messageId":"CALnO6CCQhTR77nvjPM-fhTm9o6imjw9Erk0NMWhLMYrSAWW8hw@mail.gmail.com","threadId":"64194","inReplyTo":"f69d2e6fabbace9ae76cb3822b063a3f19622138.1758656702.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/4] doc: git-pull: move and params","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-09-24T20:17:28Z","receivedAt":"2025-09-24T20:17:41Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Tue, Sep 23, 2025 at 3:45 PM Julia Evans via GitGitGadget\n wrote:\n>\n> From: Julia Evans \n>\n> From user feedback:\n>\n> - it's confusing that we use both and to refer to the\n> second argument\n\nYep.\n\n> - one user is not clear about what `refs/heads/*:refs/remotes/origin/*`\n> is meant to be an example of (\"is it like a path?\")\n\nAlso yep, since the deleted text doesn't contain any pointers to learn\nwhat a refspec is.\n\n> The DESCRIPTION section is also doing a lot right now: it's trying to\n> describe both how the and arguments work (which\n> is pretty complex, as seen in the DEFAULT BEHAVIOUR section)\n> as well as how `git pull` calls `git fetch` and merge/rebase/etc\n> depending on the arguments.\n>\n> Handle this by moving the description of the and \n> arguments to the OPTIONS section, so that we can focus on the\n> merge/rebase/etc behaviour in the DESCRIPTION section, and refer folks\n> to the later sections for details.\n\nI generally like this: it makes things a bit more consistent, even\nthough \"options\" isn't quite how I think of these (optional!)\npositional parameters. Still, I generally jump down to the \nsections (like in git-push(1)) to learn what I can do with those.\n\n> Use the term \"upstream\" instead of 'the \"remote\" and \"merge\"\n> configuration for the current branch' since users are more likely to\n> know what an \"upstream\" is.\n\nWith the upstream section, great.\n\n> diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\n> index 48e924a10a..50af7fde81 100644\n> --- a/Documentation/git-pull.adoc\n> +++ b/Documentation/git-pull.adoc\n> @@ -27,17 +27,6 @@ and then depending on configuration options or command line flags,\n> will call either `git rebase` or `git merge` to reconcile diverging\n> branches.\n>\n> - should be the name of a remote repository as\n> -passed to linkgit:git-fetch[1]. can name an\n> -arbitrary remote ref (for example, the name of a tag) or even\n> -a collection of refs with corresponding remote-tracking branches\n> -(e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}),\n> -but usually it is the name of a branch in the remote repository.\n> -\n> -Default values for and are read from the\n> -\"remote\" and \"merge\" configuration for the current branch\n> -as set by linkgit:git-branch[1] `--track`.\n\nAnd we don't even mind losing \"--track\" here because we cover it in\nUpstream Branches (e.g.,\nhttps://lore.kernel.org/git/3ecfb5c3a67723f160e8161e212d77f95964539c.1758649472.git.gitgitgadget@gmail.com/).\n\n> -\n> Assume the following history exists and the current branch is\n> \"`master`\":\n>\n> @@ -77,6 +66,24 @@ pulling or stash them away with linkgit:git-stash[1].\n> OPTIONS\n> -------\n>\n> +::\n> + The \"remote\" repository to pull from. This can be either\n> + a URL (see the section <> below) or the name\n> + of a remote (see the section <> below).\n> ++\n> +Defaults to the configured upstream for the current branch, or `origin`.\n> +See UPSTREAM BRANCHES below for more on how to configure upstreams.\n> +\n> +::\n> + Which branch or other reference(s) to fetch and integrate into the\n> + current branch, for example `main` in `git pull origin main`.\n> + Defaults to the configured upstream for the current branch.\n> ++\n> +This can be a branch, tag, or other collection of reference(s).\n> +See below under \"Options related to fetching\" for the full syntax,\n> +and DEFAULT BEHAVIOUR below for how `git pull` uses this argument to\n> +determine which remote branch to integrate.\n> +\n\nI think these are covered in Documentation/pull-fetch-param.adoc,\nwhich I only found by looking at \"git help pull\" and searching for the\nURLs references, hah.\n\nAnyway, the existing explanations are far too late in the manual (Vim\nsays ~46%, 960 lines down, when rendered with MANWIDTH=80). Moving\nthem up is a good idea, but maybe we need to do that in a way that\njives with the later \"fetching\" section. Hm.\n\n-- \nD. Ben Knoble\n"},{"id":"527256","messageId":"CALnO6CCkWaxZKGseHR7dk20erFPAvGMqO+OYr3Np+y+=1Y34HA@mail.gmail.com","threadId":"64194","inReplyTo":"ffbb9d7c6aff77f9a1caed86a20bcc6b9afe66e7.1758656702.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 2/4] doc: git-pull: clarify options for integrating remote branch","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-09-24T20:23:09Z","receivedAt":"2025-09-24T20:23:22Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Tue, Sep 23, 2025 at 3:48 PM Julia Evans via GitGitGadget\n wrote:\n>\n> From: Julia Evans \n>\n> From user feedback:\n>\n> - One user is confused about the current default (\"I was convinced that\n> the git default was still to merge on pull\")\n> - One user is confused about why \"git fetch\" isn't mentioned earlier\n> - One user says they always forget what the arguments to `git pull` are\n> and that it's not immediately obvious that `--no-rebase` means \"merge\"\n> - One user wants `--ff-only` to be mentioned\n>\n> Resolve this by listing the options for integrating the the remote\n> branch. This should help users figure out at a glance which one they\n> want to do, and make it clearer that --ff-only is the default.\n>\n> Signed-off-by: Julia Evans \n> ---\n> Documentation/git-pull.adoc | 25 ++++++++++++++-----------\n> 1 file changed, 14 insertions(+), 11 deletions(-)\n>\n> diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\n> index 50af7fde81..61d18fef36 100644\n> --- a/Documentation/git-pull.adoc\n> +++ b/Documentation/git-pull.adoc\n> @@ -15,17 +15,20 @@ SYNOPSIS\n> DESCRIPTION\n> -----------\n>\n> -Incorporates changes from a remote repository into the current branch.\n> -If the current branch is behind the remote, then by default it will\n> -fast-forward the current branch to match the remote. If the current\n> -branch and the remote have diverged, the user needs to specify how to\n> -reconcile the divergent branches with `--rebase` or `--no-rebase` (or\n> -the corresponding configuration option in `pull.rebase`).\n> -\n> -More precisely, `git pull` runs `git fetch` with the given parameters\n> -and then depending on configuration options or command line flags,\n> -will call either `git rebase` or `git merge` to reconcile diverging\n> -branches.\n> +Integrate changes from a remote repository into the current branch.\n> +\n> +First, `git pull` runs `git fetch` with the same arguments to fetch\n\nHm. Is it worth saying \"similar\" rather than \"same\" since we don't\npass e.g. `--rebase` to `git fetch`? Or is that detail unimportant in\nthis context?\n\n> +remote branch(es). Then it integrates the remote branch into the current\n> +branch.\n\nPlural-singular here leaves me wondering how Git decides which of\nmultiple fetched branches to integrate. A quick test of the form\n\n git pull origin refs/heads/\\*:refs/remotes/origin/\\*\n\njust gives an error in every mode I tried, so I'm now confused about this use :)\n\nI _do_ like that when I \"git pull\", Git will fetch all branches if I\nhave fetch.all set. That seems related but different. Welp, more\ncorners to explore!\n\n> There are 4 main options for integrating the remote branch:\n> +\n> +1. `git pull --ff-only` will only do \"fast-forward\" updates: it\n> + fails if the remote branch has diverged. This is the default.\n> +2. `git pull --rebase` runs `git rebase`\n> +3. `git pull --no-rebase` runs `git merge`.\n> +4. `git pull --squash` runs `git merge --squash`\n> +\n> +You can also set the configuration options `pull.rebase`, `pull.squash`,\n> +or `pull.ff` with your preferred behaviour.\n\nLovely.\n\n-- \nD. Ben Knoble\n"},{"id":"527257","messageId":"CALnO6CDpduG3UNMAPCBx8+du1k8Af6A-=kxhRuzooyQn8mZhzg@mail.gmail.com","threadId":"64194","inReplyTo":"c7f09c2bd32baf9e1dda355656bba811484e90a0.1758656702.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 4/4] doc: git-pull: clarify how to exit a conflicted merge","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-09-24T20:29:41Z","receivedAt":"2025-09-24T20:29:54Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Tue, Sep 23, 2025 at 3:48 PM Julia Evans via GitGitGadget\n wrote:\n>\n> From: Julia Evans \n>\n> From user feedback:\n>\n> - One user is confused about why `git reset --merge`\n> (why not just `git reset`?). Handle this by mentioning\n> `git merge --abort` and `git reset --abort` instead, which have a\n> more obvious meaning.\n\n\"git reset --merge\" _can_ be helpful when merging, but won't fully\nabort a rebase. Great.\n\n> --- a/Documentation/git-pull.adoc\n> +++ b/Documentation/git-pull.adoc\n> @@ -30,15 +30,9 @@ branch. There are 4 main options for integrating the remote branch:\n> You can also set the configuration options `pull.rebase`, `pull.squash`,\n> or `pull.ff` with your preferred behaviour.\n>\n> -In Git 1.7.0 or later, to cancel a conflicting merge, use\n> -`git reset --merge`. *Warning*: In older versions of Git, running 'git pull'\n> -with uncommitted changes is discouraged: while possible, it leaves you\n> -in a state that may be hard to back out of in the case of a conflict.\n> -\n> -If any of the remote changes overlap with local uncommitted changes,\n> -the merge will be automatically canceled and the work tree untouched.\n> -It is generally best to get any local changes in working order before\n> -pulling or stash them away with linkgit:git-stash[1].\n> +If there's a merge conflict during the merge or rebase that you don't\n> +want to handle, you can safely abort it with `git merge --abort` or `git\n> +--rebase abort`.\n\nThis information is also mentioned in the advice given by conflicts\n(and git status), so while I originally wondered if we need to say \"to\nknow which to use, run…\", I now think we can trust users to know\nwhether they asked for a merge or rebase and read the advice/git\nstatus output when they don't.\n\nHah, just kidding. Nobody* reads that output. But I still don't think\nit's worth muddying here, because the same folks are unlikely to see\nthe help here, right? Or maybe we say \"Information in `git status`\nwill summarize these options for you.\" ?\n\n[*] Obviously untrue, but you all know what I mean\n\n-- \nD. Ben Knoble\n"},{"id":"527260","messageId":"f6dea581-04c5-4b05-ab81-1fb06de1cf41@app.fastmail.com","threadId":"64194","inReplyTo":"CALnO6CCkWaxZKGseHR7dk20erFPAvGMqO+OYr3Np+y+=1Y34HA@mail.gmail.com","subject":"Re: [PATCH 2/4] doc: git-pull: clarify options for integrating remote branch","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-09-24T20:54:40Z","receivedAt":"2025-09-24T20:55:02Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n>> -More precisely, `git pull` runs `git fetch` with the given parameters\n>> -and then depending on configuration options or command line flags,\n>> -will call either `git rebase` or `git merge` to reconcile diverging\n>> -branches.\n>> +Integrate changes from a remote repository into the current branch.\n>> +\n>> +First, `git pull` runs `git fetch` with the same arguments to fetch\n>\n> Hm. Is it worth saying \"similar\" rather than \"same\" since we don't\n> pass e.g. `--rebase` to `git fetch`? Or is that detail unimportant in\n> this context?\n\nThat's a good point, I'll try to think of a better way to phrase it.\n\nI guess the truth is that `git pull` has three categories of options, \nthose it passes verbatim to `git fetch`, those it passes verbatim to `git merge`,\nand the others (-q, -v, and --recurse-submodules).\nThat's a bit of a mouthful but maybe there's a way to say that explicitly\nthat isn't too awkward, it does seem helpful to know when reading the\nOPTIONS section.\n\n>> +remote branch(es). Then it integrates the remote branch into the current\n>> +branch.\n>\n> Plural-singular here leaves me wondering how Git decides which of\n> multiple fetched branches to integrate. A quick test of the form\n>\n> git pull origin refs/heads/\\*:refs/remotes/origin/\\*\n>\n> just gives an error in every mode I tried, so I'm now confused about this use :)\n\nI find it confusing too. My current strategy for handling this here is to\nsomewhat awkwardly say \"it's explained in the DEFAULT BEHAVIOUR section\"\na bit further down.\n\nIt's a tricky situation because I find the DEFAULT BEHAVIOUR section very\nconfusing. It seems like there's a fair amount of duplication with other\nsections that could be cleaned up to make it easier. But removing the\nduplication and making it easier to understand feels like too many changes\nfor this series, especially because really doing it well probably involves the\nsub-project of \"clean up the section of the `git fetch` man page\".\n\nIn any case, I'll see if I can find a way to make it a little less awkward.\n"},{"id":"527275","messageId":"CAPx1GvfK5ZKUG86n=DR8LeO_STwO5FAkDzzD9t6d9R22KdOySg@mail.gmail.com","threadId":"64194","inReplyTo":"CALnO6CCkWaxZKGseHR7dk20erFPAvGMqO+OYr3Np+y+=1Y34HA@mail.gmail.com","subject":"Re: [PATCH 2/4] doc: git-pull: clarify options for integrating remote branch","fromName":"Chris Torek","fromEmail":"chris.torek@gmail.com","sentAt":"2025-09-24T22:38:51Z","receivedAt":"2025-09-24T22:39:05Z","isPatch":true,"sender":{"key":"chris.torek@gmail.com","avatar":"https://avatars.githubusercontent.com/u/16826774?v=4"},"body":"On Wed, Sep 24, 2025 at 1:23 PM D. Ben Knoble wrote:\n> > +First, `git pull` runs `git fetch` with the same arguments to fetch\n>\n> Hm. Is it worth saying \"similar\" rather than \"same\" since we don't\n> pass e.g. `--rebase` to `git fetch`? Or is that detail unimportant in\n> this context?\n\nI would suggest \"equivalent\" or (perhaps better) \"appropriate\".\nPerhaps even:\n\n First, `git pull` runs the equivalent of `git fetch` with the\n arguments needed to fetch necessary branches from\n the remote ...\n\nDefinition of these arguments can be deferred (perhaps\neven indefinitely); but:\n\n> > +remote branch(es). Then it integrates the remote branch into the current\n> > +branch.\n>\n> Plural-singular here leaves me wondering how Git decides which of\n> multiple fetched branches to integrate.\n\nhere we'd need something along the lines of:\n\n Then it integrates the appropriate remote branch ...\n\nand here we *do* have to define \"appropriate\".\n\n(Historically the merge step grabbed stuff from FETCH_HEAD,\nexcluding all the \"not-for-merge\" parts, and I have never dug into\nwhat happens now...)\n\nChris\n"},{"id":"528040","messageId":"6c8790b7-2b8c-4452-bcc6-2fa17d08ec86@app.fastmail.com","threadId":"64194","inReplyTo":"CAPx1GvfK5ZKUG86n=DR8LeO_STwO5FAkDzzD9t6d9R22KdOySg@mail.gmail.com","subject":"Re: [PATCH 2/4] doc: git-pull: clarify options for integrating remote branch","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-10-06T21:16:44Z","receivedAt":"2025-10-06T21:17:05Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Wed, Sep 24, 2025, at 6:38 PM, Chris Torek wrote:\n> On Wed, Sep 24, 2025 at 1:23 PM D. Ben Knoble wrote:\n>> > +First, `git pull` runs `git fetch` with the same arguments to fetch\n>>\n>> Hm. Is it worth saying \"similar\" rather than \"same\" since we don't\n>> pass e.g. `--rebase` to `git fetch`? Or is that detail unimportant in\n>> this context?\n>\n> I would suggest \"equivalent\" or (perhaps better) \"appropriate\".\n> Perhaps even:\n>\n> First, `git pull` runs the equivalent of `git fetch` with the\n> arguments needed to fetch necessary branches from\n> the remote ...\n>\n> Definition of these arguments can be deferred (perhaps\n> even indefinitely); but:\n>\n>> > +remote branch(es). Then it integrates the remote branch into the current\n>> > +branch.\n>>\n>> Plural-singular here leaves me wondering how Git decides which of\n>> multiple fetched branches to integrate.\n>\n> here we'd need something along the lines of:\n>\n> Then it integrates the appropriate remote branch ...\n>\n> and here we *do* have to define \"appropriate\".\n\nI like the idea of adding \"appropriate\" here. The question of how to define\nit is a little messy.\n\nWe do define \"appropriate\" below under , like this:\n\n> See below under \"Options related to fetching\" for the full syntax,\n> and DEFAULT BEHAVIOUR below for how `git pull` uses this argument to\n> determine which remote branch to integrate.\n\nLike I mentioned in another reply I think deferring the question of what \"the\nappropriate branch\" is to the DEFAULT BEHAVIOUR section like this does is not\na \"good\" long-term solution because that section is so confusing, but I think\nit's not worse than the current state and I don't want to expand the scope of\nthis patch series too much.\n\nHowever! I think there's a question of what behaviour to \"encourage\".\nOver on the `git push` side, we decided to highlight using\n`git push origin main` to push, because the behaviour of `git push origin main`\nis simple to explain (\"it pushes the local main branch to the main on the `origin`\nremote\").\n\nSo a natural next question is: should we equivalently highlight\n\"git pull origin main\", to mirror the `git push` man page?\nThen it would be easy to say what \"the appropriate branch\" is, because in that\ncase the branch is \"whatever branch you specified\"\n\nMy initial instinct is \"no\": `git push origin main` also feels sort of \"foolproof\" to me,\nin the sense that if you accidentally run it while on the wrong branch, nothing\nreally bad will happen, since it doesn't matter what your current branch is.\n\nBut `git pull` is not the same, since running `git pull origin ` will\nintegrate into your current branch, which could get confusing if\nyou accidentally pulled while on the wrong branch. Personally I use `git pull`\nwithout any arguments, and it feels safer to me that way because I know that I'm\nlikely to have set my upstream to something reasonable.\n\nI also did some extremely informal and low-sample-size Mastodon polling\nand my sense so far is that folks tend to run `git pull` with no arguments in\npractice. So I think it makes sense to highlight the no-arguments version.\n\nAnd in any case if you want to get really specific about what you're pulling I\nthink going straight to \"manually fetch and then run `git merge` yourself\" is\na safer approach instead of passing arguments to `git pull`.\n\nAll of that is to say: my best idea for how to resolve all of this is as follows:\n\n> First, `git pull` runs `git fetch` with the same arguments\n> (excluding merge options) to fetch remote branch(es).\n> Then it decides which remote branch to integrate: if you run `git pull`\n> with no arguments this defaults to the upstream for the current branch.\n> Then it integrates that branch into the current branch.\n\nThis explains what the \"appropriate branch\" is in (I think) the most common\nuse case and deals with the \"same arguments\" issue.\n"},{"id":"528166","messageId":"74f8a51f-f62d-4f85-89b0-f701338c7550@app.fastmail.com","threadId":"64194","inReplyTo":"CALnO6CDpduG3UNMAPCBx8+du1k8Af6A-=kxhRuzooyQn8mZhzg@mail.gmail.com","subject":"Re: [PATCH 4/4] doc: git-pull: clarify how to exit a conflicted merge","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-10-07T21:01:38Z","receivedAt":"2025-10-07T21:01:59Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Wed, Sep 24, 2025, at 4:29 PM, D. Ben Knoble wrote:\n> On Tue, Sep 23, 2025 at 3:48 PM Julia Evans via GitGitGadget\n> wrote:\n>>\n>> From: Julia Evans \n>>\n>> From user feedback:\n>>\n>> - One user is confused about why `git reset --merge`\n>> (why not just `git reset`?). Handle this by mentioning\n>> `git merge --abort` and `git reset --abort` instead, which have a\n>> more obvious meaning.\n>\n> \"git reset --merge\" _can_ be helpful when merging, but won't fully\n> abort a rebase. Great.\n>\n>> --- a/Documentation/git-pull.adoc\n>> +++ b/Documentation/git-pull.adoc\n>> @@ -30,15 +30,9 @@ branch. There are 4 main options for integrating the remote branch:\n>> You can also set the configuration options `pull.rebase`, `pull.squash`,\n>> or `pull.ff` with your preferred behaviour.\n>>\n>> -In Git 1.7.0 or later, to cancel a conflicting merge, use\n>> -`git reset --merge`. *Warning*: In older versions of Git, running 'git pull'\n>> -with uncommitted changes is discouraged: while possible, it leaves you\n>> -in a state that may be hard to back out of in the case of a conflict.\n>> -\n>> -If any of the remote changes overlap with local uncommitted changes,\n>> -the merge will be automatically canceled and the work tree untouched.\n>> -It is generally best to get any local changes in working order before\n>> -pulling or stash them away with linkgit:git-stash[1].\n>> +If there's a merge conflict during the merge or rebase that you don't\n>> +want to handle, you can safely abort it with `git merge --abort` or `git\n>> +--rebase abort`.\n>\n> This information is also mentioned in the advice given by conflicts\n> (and git status), so while I originally wondered if we need to say \"to\n> know which to use, run…\", I now think we can trust users to know\n> whether they asked for a merge or rebase and read the advice/git\n> status output when they don't.\n>\n> Hah, just kidding. Nobody* reads that output. But I still don't think\n> it's worth muddying here, because the same folks are unlikely to see\n> the help here, right? Or maybe we say \"Information in `git status`\n> will summarize these options for you.\" ?\n\nI think it's a nice way to reiterate that `git pull` is running a merge or\nrebase under the hood, but if folks feel strongly that this isn't relevant\nI'd be happy to remove the `git merge --abort` / `git rebase --abort` note.\n"},{"id":"528168","messageId":"9091705b-e575-48d7-95a0-5e2835fb9edf@app.fastmail.com","threadId":"64194","inReplyTo":"CALnO6CCQhTR77nvjPM-fhTm9o6imjw9Erk0NMWhLMYrSAWW8hw@mail.gmail.com","subject":"Re: [PATCH 1/4] doc: git-pull: move and params","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-10-07T21:20:52Z","receivedAt":"2025-10-07T21:21:13Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Wed, Sep 24, 2025, at 4:17 PM, D. Ben Knoble wrote:\n> On Tue, Sep 23, 2025 at 3:45 PM Julia Evans via GitGitGadget\n> wrote:\n>>\n>> From: Julia Evans \n>>\n>> From user feedback:\n>>\n>> - it's confusing that we use both and to refer to the\n>> second argument\n>\n> Yep.\n>\n>> - one user is not clear about what `refs/heads/*:refs/remotes/origin/*`\n>> is meant to be an example of (\"is it like a path?\")\n>\n> Also yep, since the deleted text doesn't contain any pointers to learn\n> what a refspec is.\n>\n>> The DESCRIPTION section is also doing a lot right now: it's trying to\n>> describe both how the and arguments work (which\n>> is pretty complex, as seen in the DEFAULT BEHAVIOUR section)\n>> as well as how `git pull` calls `git fetch` and merge/rebase/etc\n>> depending on the arguments.\n>>\n>> Handle this by moving the description of the and \n>> arguments to the OPTIONS section, so that we can focus on the\n>> merge/rebase/etc behaviour in the DESCRIPTION section, and refer folks\n>> to the later sections for details.\n>\n> I generally like this: it makes things a bit more consistent, even\n> though \"options\" isn't quite how I think of these (optional!)\n> positional parameters. Still, I generally jump down to the \n> sections (like in git-push(1)) to learn what I can do with those.\n>\n>> Use the term \"upstream\" instead of 'the \"remote\" and \"merge\"\n>> configuration for the current branch' since users are more likely to\n>> know what an \"upstream\" is.\n>\n> With the upstream section, great.\n>\n>> diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\n>> index 48e924a10a..50af7fde81 100644\n>> --- a/Documentation/git-pull.adoc\n>> +++ b/Documentation/git-pull.adoc\n>> @@ -27,17 +27,6 @@ and then depending on configuration options or command line flags,\n>> will call either `git rebase` or `git merge` to reconcile diverging\n>> branches.\n>>\n>> - should be the name of a remote repository as\n>> -passed to linkgit:git-fetch[1]. can name an\n>> -arbitrary remote ref (for example, the name of a tag) or even\n>> -a collection of refs with corresponding remote-tracking branches\n>> -(e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}),\n>> -but usually it is the name of a branch in the remote repository.\n>> -\n>> -Default values for and are read from the\n>> -\"remote\" and \"merge\" configuration for the current branch\n>> -as set by linkgit:git-branch[1] `--track`.\n>\n> And we don't even mind losing \"--track\" here because we cover it in\n> Upstream Branches (e.g.,\n> https://lore.kernel.org/git/3ecfb5c3a67723f160e8161e212d77f95964539c.1758649472.git.gitgitgadget@gmail.com/).\n>\n>> -\n>> Assume the following history exists and the current branch is\n>> \"`master`\":\n>>\n>> @@ -77,6 +66,24 @@ pulling or stash them away with linkgit:git-stash[1].\n>> OPTIONS\n>> -------\n>>\n>> +::\n>> + The \"remote\" repository to pull from. This can be either\n>> + a URL (see the section <> below) or the name\n>> + of a remote (see the section <> below).\n>> ++\n>> +Defaults to the configured upstream for the current branch, or `origin`.\n>> +See UPSTREAM BRANCHES below for more on how to configure upstreams.\n>> +\n>> +::\n>> + Which branch or other reference(s) to fetch and integrate into the\n>> + current branch, for example `main` in `git pull origin main`.\n>> + Defaults to the configured upstream for the current branch.\n>> ++\n>> +This can be a branch, tag, or other collection of reference(s).\n>> +See below under \"Options related to fetching\" for the full syntax,\n>> +and DEFAULT BEHAVIOUR below for how `git pull` uses this argument to\n>> +determine which remote branch to integrate.\n>> +\n>\n> I think these are covered in Documentation/pull-fetch-param.adoc,\n> which I only found by looking at \"git help pull\" and searching for the\n> URLs references, hah.\n>\n> Anyway, the existing explanations are far too late in the manual (Vim\n> says ~46%, 960 lines down, when rendered with MANWIDTH=80). Moving\n> them up is a good idea, but maybe we need to do that in a way that\n> jives with the later \"fetching\" section. Hm.\n\nThat's a good point. It's a bit weird because (I think) `git pull does use the \n parameter after passing it to `git fetch` (to decide which\nremote branch to merge), so we can't just say \"to know what the refspec\nparameter does, see \"git fetch\", and we can't just copy the existing\n section further up.\n\nRewriting the section of `git fetch` so that it addresses both the\n`git pull` and `git fetch` case seems like it would just add more confusion.\n\nDuplicating the content of the bit and then referencing \nthe second section below is the least bad option I can think of\nright now, since most of the time you don't actually need to know how to\nwrite a refspec.\n\nI'll add some internal links in the HTML version to the \nand DEFAULT BEHAVIOUR sections so that they'll be easier to find in the\nHTML version at least.\n"},{"id":"528292","messageId":"pull.1976.v2.git.1759951536.gitgitgadget@gmail.com","threadId":"64194","inReplyTo":"pull.1976.git.1758656702.gitgitgadget@gmail.com","subject":"[PATCH v2 0/4] doc: git-pull: clarify DESCRIPTION section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-10-08T19:25:32Z","receivedAt":"2025-10-08T19:25:38Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"I got feedback from 15 Git users on the current git pull man page, using\nthis tool: https://text-feedback.wizardzines.com/git-pull.\n\nMy goals here are to be clear about the relationship between git pull and\nfetch/merge/rebase etc, make sure users know the current default for git\npull (--ff-only) since some folks still remember the old default, and to\nhelp users quickly figure out what command they need to run to\nmerge/rebase/squash/etc.\n\nI've taken a pretty aggressive approach because I think it's possible to\nhave a pretty short and focused DESCRIPTION section here while keeping the\nmost important info. Open to hearing that I've removed too much.\n\nThis references the UPSTREAM BRANCHES section from\nhttps://lore.kernel.org/git/0ec629d4037bf5d1ccc248ca1bbd87ccc08119a3.1757703309.git.gitgitgadget@gmail.com/\n, so if that isn't merged I'll need to revisit the approach here.\n\nchanges in v2:\n\n * Add \"(excluding merge options)\" to clarify which options are passed to\n git fetch (from Chris's review)\n * Say that git pull will by default merge the upstream branch. (from\n Chris's review)\n * Add some links to the UPSTREAM BRANCHES section, and to the \n section in git fetch, to make it easier to navigate in the HTML version\n of the docs at least. The situation where we repeat the part\n in git fetch is weird but I don't have a better idea for how to handle it\n right now. The UPSTREAM BRANCHES links are currently failing the\n documentation tests, but should pass once the patch series that adds that\n is merged. (from Ben's review)\n\nJulia Evans (4):\n doc: git-pull: move and params\n doc: git-pull: clarify options for integrating remote branch\n doc: git-pull: delete the example\n doc: git-pull: clarify how to exit a conflicted merge\n\n Documentation/git-pull.adoc | 92 ++++++++++++-----------------\n Documentation/pull-fetch-param.adoc | 1 +\n 2 files changed, 40 insertions(+), 53 deletions(-)\n\n\nbase-commit: ca2559c1d630eb4f04cdee2328aaf1c768907a9e\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1976%2Fjvns%2Fclarify-pull-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1976/jvns/clarify-pull-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/1976\n\nRange-diff vs v1:\n\n 1: f69d2e6fab ! 1: 4cc87ec354 doc: git-pull: move and params\n @@ Documentation/git-pull.adoc: pulling or stash them away with linkgit:git-stash[1\n +\tof a remote (see the section <> below).\n ++\n +Defaults to the configured upstream for the current branch, or `origin`.\n -+See UPSTREAM BRANCHES below for more on how to configure upstreams.\n ++See <> below for more on how to\n ++configure upstreams.\n +\n +::\n +\tWhich branch or other reference(s) to fetch and integrate into the\n @@ Documentation/git-pull.adoc: pulling or stash them away with linkgit:git-stash[1\n +\tDefaults to the configured upstream for the current branch.\n ++\n +This can be a branch, tag, or other collection of reference(s).\n -+See below under \"Options related to fetching\" for the full syntax,\n -+and DEFAULT BEHAVIOUR below for how `git pull` uses this argument to\n -+determine which remote branch to integrate.\n ++See <>> below under \"Options related to fetching\"\n ++for the full syntax, and <> below\n ++for how `git pull` uses this argument to determine which remote branch\n ++to integrate.\n +\n -q::\n --quiet::\n \tThis is passed to both underlying git-fetch to squelch reporting of\n +@@ Documentation/git-pull.adoc: include::urls-remotes.adoc[]\n + \n + include::merge-strategies.adoc[]\n + \n ++[[DEFAULT-BEHAVIOUR]]\n + DEFAULT BEHAVIOUR\n + -----------------\n + \n +\n + ## Documentation/pull-fetch-param.adoc ##\n +@@ Documentation/pull-fetch-param.adoc: ifndef::git-pull[]\n + \t(See linkgit:git-config[1]).\n + endif::git-pull[]\n + \n ++[[fetch-refspec]]\n + ::\n + \tSpecifies which refs to fetch and which local refs to update.\n + \tWhen no s appear on the command line, the refs to fetch\n 2: ffbb9d7c6a ! 2: 122774d4cc doc: git-pull: clarify options for integrating remote branch\n @@ Documentation/git-pull.adoc: SYNOPSIS\n -branches.\n +Integrate changes from a remote repository into the current branch.\n +\n -+First, `git pull` runs `git fetch` with the same arguments to fetch\n -+remote branch(es). Then it integrates the remote branch into the current\n -+branch. There are 4 main options for integrating the remote branch:\n ++First, `git pull` runs `git fetch` with the same arguments\n ++(excluding merge options) to fetch remote branch(es).\n ++Then it decides which remote branch to integrate: if you run `git pull`\n ++with no arguments this defaults to the <>\n ++for the current branch.\n ++Then it integrates that branch into the current branch.\n ++\n ++There are 4 main options for integrating the remote branch:\n +\n +1. `git pull --ff-only` will only do \"fast-forward\" updates: it\n + fails if the remote branch has diverged. This is the default.\n 3: 76dc2c19fb ! 3: 323e81f2fd doc: git-pull: delete the example\n @@ Commit message\n Signed-off-by: Julia Evans \n \n ## Documentation/git-pull.adoc ##\n -@@ Documentation/git-pull.adoc: branch. There are 4 main options for integrating the remote branch:\n +@@ Documentation/git-pull.adoc: There are 4 main options for integrating the remote branch:\n You can also set the configuration options `pull.rebase`, `pull.squash`,\n or `pull.ff` with your preferred behaviour.\n \n 4: c7f09c2bd3 ! 4: 999dfba156 doc: git-pull: clarify how to exit a conflicted merge\n @@ Commit message\n Signed-off-by: Julia Evans \n \n ## Documentation/git-pull.adoc ##\n -@@ Documentation/git-pull.adoc: branch. There are 4 main options for integrating the remote branch:\n +@@ Documentation/git-pull.adoc: There are 4 main options for integrating the remote branch:\n You can also set the configuration options `pull.rebase`, `pull.squash`,\n or `pull.ff` with your preferred behaviour.\n \n\n-- \ngitgitgadget\n"},{"id":"528293","messageId":"4cc87ec354f7b9ec599d70046f3263363546bebe.1759951536.git.gitgitgadget@gmail.com","threadId":"64194","inReplyTo":"pull.1976.v2.git.1759951536.gitgitgadget@gmail.com","subject":"[PATCH v2 1/4] doc: git-pull: move and params","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-10-08T19:25:33Z","receivedAt":"2025-10-08T19:25:39Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nFrom user feedback:\n\n- it's confusing that we use both and to refer to the\n second argument\n- one user is not clear about what `refs/heads/*:refs/remotes/origin/*`\n is meant to be an example of (\"is it like a path?\")\n\nThe DESCRIPTION section is also doing a lot right now: it's trying to\ndescribe both how the and arguments work (which\nis pretty complex, as seen in the DEFAULT BEHAVIOUR section)\nas well as how `git pull` calls `git fetch` and merge/rebase/etc\ndepending on the arguments.\n\nHandle this by moving the description of the and \narguments to the OPTIONS section, so that we can focus on the\nmerge/rebase/etc behaviour in the DESCRIPTION section, and refer folks\nto the later sections for details.\n\nUse the term \"upstream\" instead of 'the \"remote\" and \"merge\"\nconfiguration for the current branch' since users are more likely to\nknow what an \"upstream\" is.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-pull.adoc | 32 +++++++++++++++++++----------\n Documentation/pull-fetch-param.adoc | 1 +\n 2 files changed, 22 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex 48e924a10a..a3d248dd1d 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -27,17 +27,6 @@ and then depending on configuration options or command line flags,\n will call either `git rebase` or `git merge` to reconcile diverging\n branches.\n \n- should be the name of a remote repository as\n-passed to linkgit:git-fetch[1]. can name an\n-arbitrary remote ref (for example, the name of a tag) or even\n-a collection of refs with corresponding remote-tracking branches\n-(e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}),\n-but usually it is the name of a branch in the remote repository.\n-\n-Default values for and are read from the\n-\"remote\" and \"merge\" configuration for the current branch\n-as set by linkgit:git-branch[1] `--track`.\n-\n Assume the following history exists and the current branch is\n \"`master`\":\n \n@@ -77,6 +66,26 @@ pulling or stash them away with linkgit:git-stash[1].\n OPTIONS\n -------\n \n+::\n+\tThe \"remote\" repository to pull from. This can be either\n+\ta URL (see the section <> below) or the name\n+\tof a remote (see the section <> below).\n++\n+Defaults to the configured upstream for the current branch, or `origin`.\n+See <> below for more on how to\n+configure upstreams.\n+\n+::\n+\tWhich branch or other reference(s) to fetch and integrate into the\n+\tcurrent branch, for example `main` in `git pull origin main`.\n+\tDefaults to the configured upstream for the current branch.\n++\n+This can be a branch, tag, or other collection of reference(s).\n+See <>> below under \"Options related to fetching\"\n+for the full syntax, and <> below\n+for how `git pull` uses this argument to determine which remote branch\n+to integrate.\n+\n -q::\n --quiet::\n \tThis is passed to both underlying git-fetch to squelch reporting of\n@@ -145,6 +154,7 @@ include::urls-remotes.adoc[]\n \n include::merge-strategies.adoc[]\n \n+[[DEFAULT-BEHAVIOUR]]\n DEFAULT BEHAVIOUR\n -----------------\n \ndiff --git a/Documentation/pull-fetch-param.adoc b/Documentation/pull-fetch-param.adoc\nindex d79d2f6065..bb2cf6a462 100644\n--- a/Documentation/pull-fetch-param.adoc\n+++ b/Documentation/pull-fetch-param.adoc\n@@ -11,6 +11,7 @@ ifndef::git-pull[]\n \t(See linkgit:git-config[1]).\n endif::git-pull[]\n \n+[[fetch-refspec]]\n ::\n \tSpecifies which refs to fetch and which local refs to update.\n \tWhen no s appear on the command line, the refs to fetch\n-- \ngitgitgadget\n\n"},{"id":"528294","messageId":"122774d4cc8fa4e9184a0f82e9b6e562363ea433.1759951536.git.gitgitgadget@gmail.com","threadId":"64194","inReplyTo":"pull.1976.v2.git.1759951536.gitgitgadget@gmail.com","subject":"[PATCH v2 2/4] doc: git-pull: clarify options for integrating remote branch","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-10-08T19:25:34Z","receivedAt":"2025-10-08T19:25:41Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nFrom user feedback:\n\n- One user is confused about the current default (\"I was convinced that\n the git default was still to merge on pull\")\n- One user is confused about why \"git fetch\" isn't mentioned earlier\n- One user says they always forget what the arguments to `git pull` are\n and that it's not immediately obvious that `--no-rebase` means \"merge\"\n- One user wants `--ff-only` to be mentioned\n\nResolve this by listing the options for integrating the the remote\nbranch. This should help users figure out at a glance which one they\nwant to do, and make it clearer that --ff-only is the default.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-pull.adoc | 30 +++++++++++++++++++-----------\n 1 file changed, 19 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex a3d248dd1d..6e9fa14967 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -15,17 +15,25 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-Incorporates changes from a remote repository into the current branch.\n-If the current branch is behind the remote, then by default it will\n-fast-forward the current branch to match the remote. If the current\n-branch and the remote have diverged, the user needs to specify how to\n-reconcile the divergent branches with `--rebase` or `--no-rebase` (or\n-the corresponding configuration option in `pull.rebase`).\n-\n-More precisely, `git pull` runs `git fetch` with the given parameters\n-and then depending on configuration options or command line flags,\n-will call either `git rebase` or `git merge` to reconcile diverging\n-branches.\n+Integrate changes from a remote repository into the current branch.\n+\n+First, `git pull` runs `git fetch` with the same arguments\n+(excluding merge options) to fetch remote branch(es).\n+Then it decides which remote branch to integrate: if you run `git pull`\n+with no arguments this defaults to the <>\n+for the current branch.\n+Then it integrates that branch into the current branch.\n+\n+There are 4 main options for integrating the remote branch:\n+\n+1. `git pull --ff-only` will only do \"fast-forward\" updates: it\n+ fails if the remote branch has diverged. This is the default.\n+2. `git pull --rebase` runs `git rebase`\n+3. `git pull --no-rebase` runs `git merge`.\n+4. `git pull --squash` runs `git merge --squash`\n+\n+You can also set the configuration options `pull.rebase`, `pull.squash`,\n+or `pull.ff` with your preferred behaviour.\n \n Assume the following history exists and the current branch is\n \"`master`\":\n-- \ngitgitgadget\n\n"},{"id":"528295","messageId":"323e81f2fd4efadf21bf5a77fe164d09e12665b6.1759951536.git.gitgitgadget@gmail.com","threadId":"64194","inReplyTo":"pull.1976.v2.git.1759951536.gitgitgadget@gmail.com","subject":"[PATCH v2 3/4] doc: git-pull: delete the example","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-10-08T19:25:35Z","receivedAt":"2025-10-08T19:25:42Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nFrom user feedback: this example is confusing because it implies that\n`git pull` will run `git merge` by default, but the default is\n`--ff-only`.\n\nWe could instead show an example of a fast-forward merge, but that may\nnot add a lot since fast-forward merges are relatively simple. This lets\nus keep the description short.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-pull.adoc | 26 --------------------------\n 1 file changed, 26 deletions(-)\n\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex 6e9fa14967..dc93e5e6d7 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -35,32 +35,6 @@ There are 4 main options for integrating the remote branch:\n You can also set the configuration options `pull.rebase`, `pull.squash`,\n or `pull.ff` with your preferred behaviour.\n \n-Assume the following history exists and the current branch is\n-\"`master`\":\n-\n-------------\n-\t A---B---C master on origin\n-\t /\n- D---E---F---G master\n-\t^\n-\torigin/master in your repository\n-------------\n-\n-Then \"`git pull`\" will fetch and replay the changes from the remote\n-`master` branch since it diverged from the local `master` (i.e., `E`)\n-until its current commit (`C`) on top of `master` and record the\n-result in a new commit along with the names of the two parent commits\n-and a log message from the user describing the changes.\n-\n-------------\n-\t A---B---C origin/master\n-\t / \\\n- D---E---F---G---H master\n-------------\n-\n-See linkgit:git-merge[1] for details, including how conflicts\n-are presented and handled.\n-\n In Git 1.7.0 or later, to cancel a conflicting merge, use\n `git reset --merge`. *Warning*: In older versions of Git, running 'git pull'\n with uncommitted changes is discouraged: while possible, it leaves you\n-- \ngitgitgadget\n\n"},{"id":"528296","messageId":"999dfba15610ce5d6ddc19f4512de64181184920.1759951536.git.gitgitgadget@gmail.com","threadId":"64194","inReplyTo":"pull.1976.v2.git.1759951536.gitgitgadget@gmail.com","subject":"[PATCH v2 4/4] doc: git-pull: clarify how to exit a conflicted merge","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-10-08T19:25:36Z","receivedAt":"2025-10-08T19:25:43Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nFrom user feedback:\n\n- One user is confused about why `git reset --merge`\n (why not just `git reset`?). Handle this by mentioning\n `git merge --abort` and `git reset --abort` instead, which have a\n more obvious meaning.\n- 2 users want to know what \"In older versions of Git\" means exactly\n (in versions older than 1.7.0). Handle this by removing the warning\n since it was added 15 years ago (in 3f8fc184c0e2c)\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-pull.adoc | 12 +++---------\n 1 file changed, 3 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex dc93e5e6d7..8d286425d6 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -35,15 +35,9 @@ There are 4 main options for integrating the remote branch:\n You can also set the configuration options `pull.rebase`, `pull.squash`,\n or `pull.ff` with your preferred behaviour.\n \n-In Git 1.7.0 or later, to cancel a conflicting merge, use\n-`git reset --merge`. *Warning*: In older versions of Git, running 'git pull'\n-with uncommitted changes is discouraged: while possible, it leaves you\n-in a state that may be hard to back out of in the case of a conflict.\n-\n-If any of the remote changes overlap with local uncommitted changes,\n-the merge will be automatically canceled and the work tree untouched.\n-It is generally best to get any local changes in working order before\n-pulling or stash them away with linkgit:git-stash[1].\n+If there's a merge conflict during the merge or rebase that you don't\n+want to handle, you can safely abort it with `git merge --abort` or `git\n+--rebase abort`.\n \n OPTIONS\n -------\n-- \ngitgitgadget\n"},{"id":"528328","messageId":"xmqqqzvddqon.fsf@gitster.g","threadId":"64194","inReplyTo":"122774d4cc8fa4e9184a0f82e9b6e562363ea433.1759951536.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 2/4] doc: git-pull: clarify options for integrating remote branch","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-08T21:33:28Z","receivedAt":"2025-10-08T21:33:30Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" writes:\n\n> +Integrate changes from a remote repository into the current branch.\n> +\n> +First, `git pull` runs `git fetch` with the same arguments\n> +(excluding merge options) to fetch remote branch(es).\n> +Then it decides which remote branch to integrate: if you run `git pull`\n> +with no arguments this defaults to the <>\n> +for the current branch.\n> +Then it integrates that branch into the current branch.\n> +There are 4 main options for integrating the remote branch:\n> +\n> +1. `git pull --ff-only` will only do \"fast-forward\" updates: it\n> + fails if the remote branch has diverged. This is the default.\n\nTechnically, you can pretend to be the king, the center of the\nworld, and occasionally publish your very latest to the remote by\npushing there, and it is technically possible that the remote to\ndiverge from you by somehow acquiring its own commits, so the above\nis not wrong per-se, but the way it is phrased is a bit awkward.\n\nThe operation fails when _you_ diverged from the remote branch.\n\nIn other words, you cloned or made yourself in-sync with the remote\nearlier, the remote may or may not have progressed before your\n'pull'. If you created your own commits on top of the state that\nwas in sync with them, you diverged from them and --ff-only is\nstopped in such a case. If you haven't changed your branch since\nyou were in sync with them the last time, --ff-only would\nfast-forward your branch to match what they have.\n\n> +2. `git pull --rebase` runs `git rebase`\n\nThis technically does not integrate remote branch into our current\nbranch. Rather, the commits on our current branch are integrated\non top of their history. That may be worth noting? I dunno.\n\n> +3. `git pull --no-rebase` runs `git merge`.\n> +4. `git pull --squash` runs `git merge --squash`\n> +\n> +You can also set the configuration options `pull.rebase`, `pull.squash`,\n> +or `pull.ff` with your preferred behaviour.\n\nThis part has two orthogonal things, each of which has its own\ndefault, which may be a bit confusing. (1) which branch we get from\nthe remote integrates with the current branch. The default is to\nuse the upstream of our current branch. (2) how the integration\nbetween the remote thing and our current branch is done. The\ndefault is only to accept fast-forward updates.\n\nPerhaps it may help clarify the flow if we said upfront that we\ndescribe two orthgonal things? E.g.,\n\n First it fetches. Then it decides two things: what to integrage\n with the current branch, and how to do the integration. By\n default, the upstream branch of the current branch is what gets\n integrated, and by default \"pull --ff-only\" (described below) is\n how the integration is done.\n\nor something? I dunno.\n\n"},{"id":"528407","messageId":"b432f1b9-804d-4249-bc1a-4f3629aff50c@app.fastmail.com","threadId":"64194","inReplyTo":"xmqqqzvddqon.fsf@gitster.g","subject":"Re: [PATCH v2 2/4] doc: git-pull: clarify options for integrating remote branch","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-10-09T21:31:30Z","receivedAt":"2025-10-09T21:35:48Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Wed, Oct 8, 2025, at 5:33 PM, Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" writes:\n>\n>> +Integrate changes from a remote repository into the current branch.\n>> +\n>> +First, `git pull` runs `git fetch` with the same arguments\n>> +(excluding merge options) to fetch remote branch(es).\n>> +Then it decides which remote branch to integrate: if you run `git pull`\n>> +with no arguments this defaults to the <>\n>> +for the current branch.\n>> +Then it integrates that branch into the current branch.\n>> +There are 4 main options for integrating the remote branch:\n>> +\n>> +1. `git pull --ff-only` will only do \"fast-forward\" updates: it\n>> + fails if the remote branch has diverged. This is the default.\n>\n> Technically, you can pretend to be the king, the center of the\n> world, and occasionally publish your very latest to the remote by\n> pushing there, and it is technically possible that the remote to\n> diverge from you by somehow acquiring its own commits, so the above\n> is not wrong per-se, but the way it is phrased is a bit awkward.\n>\n> The operation fails when _you_ diverged from the remote branch.\n\nThanks, I meant to fix that earlier. Will fix to say\n\"if your local branch has diverged from the remote\".\n\n\n>> +2. `git pull --rebase` runs `git rebase`\n>\n> This technically does not integrate remote branch into our current\n> branch. Rather, the commits on our current branch are integrated\n> on top of their history. That may be worth noting? I dunno.\n\nAt least 2 users who read this also commented that they find the word\n\"integrate\" using, for perhaps a similar reason. Specifically, one comment\nwas \"unclear if 'integrate' is a technical/specific term or just generic\".\n\nMy assumption was that the word \"integrate\" was meant to be a generic\nway to communicate \"combine the changes in the two branches in\nsome unspecified way\", and that's how I was using it. I'm not sure what\nyou mean when you say \"integrate\" (is it \"merge\"?).\n\nI see a few options here:\n\n1. Try to find a different word that communicates \"combine the two\n branches in a way that you have to specify\". I'm not sure how\n likely this is to succeed.\n2. Instead of using the word \"integrate\", instead always say something\n like \"merge or rebase\". I tried this but I found it a bit unwieldy, and\n I think it might also be confusing for users who aren't familiar with\n both merge and rebase, they might worry \"do I need to understand\n rebase to use `git pull`?\", when of course you don't.\n3. Keep the word \"integrate\".\n\nI'm very open to hearing suggestions here, maybe there's another\nbetter way I haven't thought of.\n\n>> +3. `git pull --no-rebase` runs `git merge`.\n>> +4. `git pull --squash` runs `git merge --squash`\n>> +\n>> +You can also set the configuration options `pull.rebase`, `pull.squash`,\n>> +or `pull.ff` with your preferred behaviour.\n>\n> This part has two orthogonal things, each of which has its own\n> default, which may be a bit confusing. (1) which branch we get from\n> the remote integrates with the current branch. The default is to\n> use the upstream of our current branch. (2) how the integration\n> between the remote thing and our current branch is done. The\n> default is only to accept fast-forward updates.\n>\n> Perhaps it may help clarify the flow if we said upfront that we\n> describe two orthgonal things? E.g.,\n>\n> First it fetches. Then it decides two things: what to integrage\n> with the current branch, and how to do the integration. By\n> default, the upstream branch of the current branch is what gets\n> integrated, and by default \"pull --ff-only\" (described below) is\n> how the integration is done.\n>\n> or something? I dunno.\n\nI think I'm happy with how the two different defaults are being\ndescribed right now, but I'll run this by some folks and see\nwhat they think.\n"},{"id":"528427","messageId":"bf769259-af30-4b13-aa0d-36c244e7502c@app.fastmail.com","threadId":"64194","inReplyTo":"b432f1b9-804d-4249-bc1a-4f3629aff50c@app.fastmail.com","subject":"Re: [PATCH v2 2/4] doc: git-pull: clarify options for integrating remote branch","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-10-09T22:20:40Z","receivedAt":"2025-10-09T22:21:02Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Thu, Oct 9, 2025, at 23:31, Julia Evans wrote:\n> On Wed, Oct 8, 2025, at 5:33 PM, Junio C Hamano wrote:\n>>>[snip]\n>>> +2. `git pull --rebase` runs `git rebase`\n>>\n>> This technically does not integrate remote branch into our current\n>> branch. Rather, the commits on our current branch are integrated\n>> on top of their history. That may be worth noting? I dunno.\n>\n> At least 2 users who read this also commented that they find the word\n> \"integrate\" using, for perhaps a similar reason. Specifically, one comment\n> was \"unclear if 'integrate' is a technical/specific term or just generic\".\n\n(confusing)\n\n>\n> My assumption was that the word \"integrate\" was meant to be a generic\n> way to communicate \"combine the changes in the two branches in\n> some unspecified way\", and that's how I was using it. I'm not sure what\n> you mean when you say \"integrate\" (is it \"merge\"?).\n\nI wonder if “integration” is like “upstream”; frequently used but not\nreally explained? (see gitworkflows(7); one mention in gitglossary(7)).\n\nI think Martin Fowler has the correct (useful) view on branches:[1]\n\n In thinking about these patterns, I find it useful to develop two\n main categories. One group looks at integration, how multiple\n developers combine their work into a coherent whole. The other looks\n at the path to production, using branching to help manage the route\n from an integrated code base to a product running in production.\n\nSpecifically the first category.\n\nThen later:\n\n Branching is about managing the interplay of isolation and\n integration. Having everyone work on a single shared codebase all\n the time, doesn't work because I can't compile the program if you're\n in the middle of typing a variable name. So at least to some degree,\n we need a notion of a private workspace that I can work on for a\n while. Modern source code controls tools make it easy to branch and\n monitor changes to those branches. At some point however we need to\n integrate. Thinking about branching strategies is really all about\n deciding how and when we integrate.\n\n🔗 1: https://martinfowler.com/articles/branching-patterns.html\n\nThe point of *most* branches ought to be this: you need isolation, but\nyou also want to eventually integrate with upstream, the trunk, or\nwhatever else.\n\n• Everyone working on everything at the same time is chaos\n• Everyone working on their own thing in isolation forever is\n Balkanization\n• Forking a private space to integrate later in a timely manner strikes\n the right balance\n• (Then there are the dozens of variations of long-living forks, private\n forks for the changes that you want to make but few others want...)\n\nSo I don’t think that\n\n> \"combine the changes in the two branches in some unspecified way\"\n\nis quite it, because the direction is towards one integration branch,\none upstream, one trunk, main branch (not whichever one).\n\n> way to communicate \"combine the changes in the two branches in\n> some unspecified way\", and that's how I was using it. I'm not sure what\n\n... and regarding “unspecified”: I suspect the contention might be\ndistinction between integrating the branchy itself (with those commits)\nwith replaying fresh commits (rebase). But I don’t know.\n\n>\n>[snip]\n"},{"id":"528429","messageId":"xmqqa51zd7gi.fsf@gitster.g","threadId":"64194","inReplyTo":"b432f1b9-804d-4249-bc1a-4f3629aff50c@app.fastmail.com","subject":"Re: [PATCH v2 2/4] doc: git-pull: clarify options for integrating remote branch","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-09T22:41:01Z","receivedAt":"2025-10-09T22:41:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" writes:\n\n> My assumption was that the word \"integrate\" was meant to be a generic\n> way to communicate \"combine the changes in the two branches in\n> some unspecified way\", and that's how I was using it.\n\nIt is how I was using it, too.\n\n> I'm not sure what\n> you mean when you say \"integrate\" (is it \"merge\"?).\n\nNot limited to \"merge\", but I view it more as between two parties,\none side supplies changes while the other side serves as a base. A\nmerge looks as if the changes of a side branch gets incorporated\ninto the trunk. A rebase looks as if the changes you have created\ngets incorporated into the trunk by replaying them onto the trunk.\n\n> 1. Try to find a different word that communicates \"combine the two\n> branches in a way that you have to specify\". I'm not sure how\n> likely this is to succeed.\n\nI am not particularly good at finding verbs, sorry.\n\n> 2. Instead of using the word \"integrate\", instead always say something\n> like \"merge or rebase\". I tried this but I found it a bit unwieldy, and\n> I think it might also be confusing for users who aren't familiar with\n> both merge and rebase, they might worry \"do I need to understand\n> rebase to use `git pull`?\", when of course you don't.\n\nVery true.\n\n"},{"id":"528442","messageId":"6B75AE20-CF68-4C98-A49C-248E2C50A756@gmail.com","threadId":"64194","inReplyTo":"74f8a51f-f62d-4f85-89b0-f701338c7550@app.fastmail.com","subject":"Re: [PATCH 4/4] doc: git-pull: clarify how to exit a conflicted merge","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-10-10T00:45:30Z","receivedAt":"2025-10-10T00:45:43Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"\n> Le 7 oct. 2025 à 17:01, Julia Evans a écrit :\n> \n> \n> \n>> On Wed, Sep 24, 2025, at 4:29 PM, D. Ben Knoble wrote:\n>>> On Tue, Sep 23, 2025 at 3:48 PM Julia Evans via GitGitGadget\n>>> wrote:\n>>> \n>>> From: Julia Evans \n>>> \n>>> From user feedback:\n>>> \n>>> - One user is confused about why `git reset --merge`\n>>> (why not just `git reset`?). Handle this by mentioning\n>>> `git merge --abort` and `git reset --abort` instead, which have a\n>>> more obvious meaning.\n>> \n>> \"git reset --merge\" _can_ be helpful when merging, but won't fully\n>> abort a rebase. Great.\n\nWhile fiddling around: turns out reset’s merge flag does abort the merge properly. TMTOWTDI, I suppose. \n\n>> \n>>> --- a/Documentation/git-pull.adoc\n>>> +++ b/Documentation/git-pull.adoc\n>>> @@ -30,15 +30,9 @@ branch. There are 4 main options for integrating the remote branch:\n>>> You can also set the configuration options `pull.rebase`, `pull.squash`,\n>>> or `pull.ff` with your preferred behaviour.\n>>> \n>>> -In Git 1.7.0 or later, to cancel a conflicting merge, use\n>>> -`git reset --merge`. *Warning*: In older versions of Git, running 'git pull'\n>>> -with uncommitted changes is discouraged: while possible, it leaves you\n>>> -in a state that may be hard to back out of in the case of a conflict.\n>>> -\n>>> -If any of the remote changes overlap with local uncommitted changes,\n>>> -the merge will be automatically canceled and the work tree untouched.\n>>> -It is generally best to get any local changes in working order before\n>>> -pulling or stash them away with linkgit:git-stash[1].\n>>> +If there's a merge conflict during the merge or rebase that you don't\n>>> +want to handle, you can safely abort it with `git merge --abort` or `git\n>>> +--rebase abort`.\n>> \n>> This information is also mentioned in the advice given by conflicts\n>> (and git status), so while I originally wondered if we need to say \"to\n>> know which to use, run…\", I now think we can trust users to know\n>> whether they asked for a merge or rebase and read the advice/git\n>> status output when they don't.\n>> \n>> Hah, just kidding. Nobody* reads that output. But I still don't think\n>> it's worth muddying here, because the same folks are unlikely to see\n>> the help here, right? Or maybe we say \"Information in `git status`\n>> will summarize these options for you.\" ?\n> \n> I think it's a nice way to reiterate that `git pull` is running a merge or\n> rebase under the hood, but if folks feel strongly that this isn't relevant\n> I'd be happy to remove the `git merge --abort` / `git rebase --abort` note.\n\nI’d probably prefer to keep the pull->{merge,rebase} implication. I just want « how do I know which one » to be clear."},{"id":"528805","messageId":"pull.1976.v3.git.1760534011.gitgitgadget@gmail.com","threadId":"64194","inReplyTo":"pull.1976.v2.git.1759951536.gitgitgadget@gmail.com","subject":"[PATCH v3 0/4] doc: git-pull: clarify DESCRIPTION section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-10-15T13:13:27Z","receivedAt":"2025-10-15T13:13:34Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"I got feedback from 15 Git users on the current git pull man page, using\nthis tool: https://text-feedback.wizardzines.com/git-pull.\n\nMy goals here are to be clear about the relationship between git pull and\nfetch/merge/rebase etc, make sure users know the current default for git\npull (--ff-only) since some folks still remember the old default, and to\nhelp users quickly figure out what command they need to run to\nmerge/rebase/squash/etc.\n\nI've taken a pretty aggressive approach because I think it's possible to\nhave a pretty short and focused DESCRIPTION section here while keeping the\nmost important info. Open to hearing that I've removed too much.\n\nThis references the UPSTREAM BRANCHES section from\nhttps://lore.kernel.org/git/0ec629d4037bf5d1ccc248ca1bbd87ccc08119a3.1757703309.git.gitgitgadget@gmail.com/\n, so if that isn't merged I'll need to revisit the approach here.\n\nchanges in v2:\n\n * Add \"(excluding merge options)\" to clarify which options are passed to\n git fetch (from Chris's review)\n * Say that git pull will by default merge the upstream branch. (from\n Chris's review)\n * Add some links to the UPSTREAM BRANCHES section, and to the \n section in git fetch, to make it easier to navigate in the HTML version\n of the docs at least. The situation where we repeat the part\n in git fetch is weird but I don't have a better idea for how to handle it\n right now. The UPSTREAM BRANCHES links are currently failing the\n documentation tests, but should pass once the patch series that adds that\n is merged. (from Ben's review)\n\nchanges in v3:\n\nChange \"fails if the local branch has diverged\" to say \"remote branch has\ndiverged\", from Junio's review.\n\nI did not come up with a better idea for a word to use than \"integrate\" so\nleft that alone.\n\nJulia Evans (4):\n doc: git-pull: move and params\n doc: git-pull: clarify options for integrating remote branch\n doc: git-pull: delete the example\n doc: git-pull: clarify how to exit a conflicted merge\n\n Documentation/git-pull.adoc | 93 +++++++++++++----------------\n Documentation/pull-fetch-param.adoc | 1 +\n 2 files changed, 41 insertions(+), 53 deletions(-)\n\n\nbase-commit: ca2559c1d630eb4f04cdee2328aaf1c768907a9e\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1976%2Fjvns%2Fclarify-pull-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1976/jvns/clarify-pull-v3\nPull-Request: https://github.com/gitgitgadget/git/pull/1976\n\nRange-diff vs v2:\n\n 1: 4cc87ec354 = 1: 96b2673e04 doc: git-pull: move and params\n 2: 122774d4cc ! 2: 0ff00b4ff6 doc: git-pull: clarify options for integrating remote branch\n @@ Documentation/git-pull.adoc: SYNOPSIS\n +There are 4 main options for integrating the remote branch:\n +\n +1. `git pull --ff-only` will only do \"fast-forward\" updates: it\n -+ fails if the remote branch has diverged. This is the default.\n ++ fails if your local branch has diverged from the remote branch.\n ++ This is the default.\n +2. `git pull --rebase` runs `git rebase`\n +3. `git pull --no-rebase` runs `git merge`.\n +4. `git pull --squash` runs `git merge --squash`\n 3: 323e81f2fd = 3: 2439c3d847 doc: git-pull: delete the example\n 4: 999dfba156 = 4: 2236dac4e4 doc: git-pull: clarify how to exit a conflicted merge\n\n-- \ngitgitgadget\n"},{"id":"528806","messageId":"96b2673e04ea151a2464fd960fac0db8c58ab8fd.1760534011.git.gitgitgadget@gmail.com","threadId":"64194","inReplyTo":"pull.1976.v3.git.1760534011.gitgitgadget@gmail.com","subject":"[PATCH v3 1/4] doc: git-pull: move and params","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-10-15T13:13:28Z","receivedAt":"2025-10-15T13:13:36Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nFrom user feedback:\n\n- it's confusing that we use both and to refer to the\n second argument\n- one user is not clear about what `refs/heads/*:refs/remotes/origin/*`\n is meant to be an example of (\"is it like a path?\")\n\nThe DESCRIPTION section is also doing a lot right now: it's trying to\ndescribe both how the and arguments work (which\nis pretty complex, as seen in the DEFAULT BEHAVIOUR section)\nas well as how `git pull` calls `git fetch` and merge/rebase/etc\ndepending on the arguments.\n\nHandle this by moving the description of the and \narguments to the OPTIONS section, so that we can focus on the\nmerge/rebase/etc behaviour in the DESCRIPTION section, and refer folks\nto the later sections for details.\n\nUse the term \"upstream\" instead of 'the \"remote\" and \"merge\"\nconfiguration for the current branch' since users are more likely to\nknow what an \"upstream\" is.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-pull.adoc | 32 +++++++++++++++++++----------\n Documentation/pull-fetch-param.adoc | 1 +\n 2 files changed, 22 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex 48e924a10a..a3d248dd1d 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -27,17 +27,6 @@ and then depending on configuration options or command line flags,\n will call either `git rebase` or `git merge` to reconcile diverging\n branches.\n \n- should be the name of a remote repository as\n-passed to linkgit:git-fetch[1]. can name an\n-arbitrary remote ref (for example, the name of a tag) or even\n-a collection of refs with corresponding remote-tracking branches\n-(e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}),\n-but usually it is the name of a branch in the remote repository.\n-\n-Default values for and are read from the\n-\"remote\" and \"merge\" configuration for the current branch\n-as set by linkgit:git-branch[1] `--track`.\n-\n Assume the following history exists and the current branch is\n \"`master`\":\n \n@@ -77,6 +66,26 @@ pulling or stash them away with linkgit:git-stash[1].\n OPTIONS\n -------\n \n+::\n+\tThe \"remote\" repository to pull from. This can be either\n+\ta URL (see the section <> below) or the name\n+\tof a remote (see the section <> below).\n++\n+Defaults to the configured upstream for the current branch, or `origin`.\n+See <> below for more on how to\n+configure upstreams.\n+\n+::\n+\tWhich branch or other reference(s) to fetch and integrate into the\n+\tcurrent branch, for example `main` in `git pull origin main`.\n+\tDefaults to the configured upstream for the current branch.\n++\n+This can be a branch, tag, or other collection of reference(s).\n+See <>> below under \"Options related to fetching\"\n+for the full syntax, and <> below\n+for how `git pull` uses this argument to determine which remote branch\n+to integrate.\n+\n -q::\n --quiet::\n \tThis is passed to both underlying git-fetch to squelch reporting of\n@@ -145,6 +154,7 @@ include::urls-remotes.adoc[]\n \n include::merge-strategies.adoc[]\n \n+[[DEFAULT-BEHAVIOUR]]\n DEFAULT BEHAVIOUR\n -----------------\n \ndiff --git a/Documentation/pull-fetch-param.adoc b/Documentation/pull-fetch-param.adoc\nindex d79d2f6065..bb2cf6a462 100644\n--- a/Documentation/pull-fetch-param.adoc\n+++ b/Documentation/pull-fetch-param.adoc\n@@ -11,6 +11,7 @@ ifndef::git-pull[]\n \t(See linkgit:git-config[1]).\n endif::git-pull[]\n \n+[[fetch-refspec]]\n ::\n \tSpecifies which refs to fetch and which local refs to update.\n \tWhen no s appear on the command line, the refs to fetch\n-- \ngitgitgadget\n\n"},{"id":"528807","messageId":"0ff00b4ff608683eafcc636a8c0c1c8b10bbe47d.1760534011.git.gitgitgadget@gmail.com","threadId":"64194","inReplyTo":"pull.1976.v3.git.1760534011.gitgitgadget@gmail.com","subject":"[PATCH v3 2/4] doc: git-pull: clarify options for integrating remote branch","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-10-15T13:13:29Z","receivedAt":"2025-10-15T13:13:37Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nFrom user feedback:\n\n- One user is confused about the current default (\"I was convinced that\n the git default was still to merge on pull\")\n- One user is confused about why \"git fetch\" isn't mentioned earlier\n- One user says they always forget what the arguments to `git pull` are\n and that it's not immediately obvious that `--no-rebase` means \"merge\"\n- One user wants `--ff-only` to be mentioned\n\nResolve this by listing the options for integrating the the remote\nbranch. This should help users figure out at a glance which one they\nwant to do, and make it clearer that --ff-only is the default.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-pull.adoc | 31 ++++++++++++++++++++-----------\n 1 file changed, 20 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex a3d248dd1d..0686a9d666 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -15,17 +15,26 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-Incorporates changes from a remote repository into the current branch.\n-If the current branch is behind the remote, then by default it will\n-fast-forward the current branch to match the remote. If the current\n-branch and the remote have diverged, the user needs to specify how to\n-reconcile the divergent branches with `--rebase` or `--no-rebase` (or\n-the corresponding configuration option in `pull.rebase`).\n-\n-More precisely, `git pull` runs `git fetch` with the given parameters\n-and then depending on configuration options or command line flags,\n-will call either `git rebase` or `git merge` to reconcile diverging\n-branches.\n+Integrate changes from a remote repository into the current branch.\n+\n+First, `git pull` runs `git fetch` with the same arguments\n+(excluding merge options) to fetch remote branch(es).\n+Then it decides which remote branch to integrate: if you run `git pull`\n+with no arguments this defaults to the <>\n+for the current branch.\n+Then it integrates that branch into the current branch.\n+\n+There are 4 main options for integrating the remote branch:\n+\n+1. `git pull --ff-only` will only do \"fast-forward\" updates: it\n+ fails if your local branch has diverged from the remote branch.\n+ This is the default.\n+2. `git pull --rebase` runs `git rebase`\n+3. `git pull --no-rebase` runs `git merge`.\n+4. `git pull --squash` runs `git merge --squash`\n+\n+You can also set the configuration options `pull.rebase`, `pull.squash`,\n+or `pull.ff` with your preferred behaviour.\n \n Assume the following history exists and the current branch is\n \"`master`\":\n-- \ngitgitgadget\n\n"},{"id":"528808","messageId":"2439c3d8474003571deaf632dddc9cf1f5478029.1760534011.git.gitgitgadget@gmail.com","threadId":"64194","inReplyTo":"pull.1976.v3.git.1760534011.gitgitgadget@gmail.com","subject":"[PATCH v3 3/4] doc: git-pull: delete the example","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-10-15T13:13:30Z","receivedAt":"2025-10-15T13:13:38Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nFrom user feedback: this example is confusing because it implies that\n`git pull` will run `git merge` by default, but the default is\n`--ff-only`.\n\nWe could instead show an example of a fast-forward merge, but that may\nnot add a lot since fast-forward merges are relatively simple. This lets\nus keep the description short.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-pull.adoc | 26 --------------------------\n 1 file changed, 26 deletions(-)\n\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex 0686a9d666..273172aa80 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -36,32 +36,6 @@ There are 4 main options for integrating the remote branch:\n You can also set the configuration options `pull.rebase`, `pull.squash`,\n or `pull.ff` with your preferred behaviour.\n \n-Assume the following history exists and the current branch is\n-\"`master`\":\n-\n-------------\n-\t A---B---C master on origin\n-\t /\n- D---E---F---G master\n-\t^\n-\torigin/master in your repository\n-------------\n-\n-Then \"`git pull`\" will fetch and replay the changes from the remote\n-`master` branch since it diverged from the local `master` (i.e., `E`)\n-until its current commit (`C`) on top of `master` and record the\n-result in a new commit along with the names of the two parent commits\n-and a log message from the user describing the changes.\n-\n-------------\n-\t A---B---C origin/master\n-\t / \\\n- D---E---F---G---H master\n-------------\n-\n-See linkgit:git-merge[1] for details, including how conflicts\n-are presented and handled.\n-\n In Git 1.7.0 or later, to cancel a conflicting merge, use\n `git reset --merge`. *Warning*: In older versions of Git, running 'git pull'\n with uncommitted changes is discouraged: while possible, it leaves you\n-- \ngitgitgadget\n\n"},{"id":"528809","messageId":"2236dac4e469a82813b71e6bc67ec29fcb78752c.1760534011.git.gitgitgadget@gmail.com","threadId":"64194","inReplyTo":"pull.1976.v3.git.1760534011.gitgitgadget@gmail.com","subject":"[PATCH v3 4/4] doc: git-pull: clarify how to exit a conflicted merge","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-10-15T13:13:31Z","receivedAt":"2025-10-15T13:13:40Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nFrom user feedback:\n\n- One user is confused about why `git reset --merge`\n (why not just `git reset`?). Handle this by mentioning\n `git merge --abort` and `git reset --abort` instead, which have a\n more obvious meaning.\n- 2 users want to know what \"In older versions of Git\" means exactly\n (in versions older than 1.7.0). Handle this by removing the warning\n since it was added 15 years ago (in 3f8fc184c0e2c)\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-pull.adoc | 12 +++---------\n 1 file changed, 3 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex 273172aa80..cd3bbc90e3 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -36,15 +36,9 @@ There are 4 main options for integrating the remote branch:\n You can also set the configuration options `pull.rebase`, `pull.squash`,\n or `pull.ff` with your preferred behaviour.\n \n-In Git 1.7.0 or later, to cancel a conflicting merge, use\n-`git reset --merge`. *Warning*: In older versions of Git, running 'git pull'\n-with uncommitted changes is discouraged: while possible, it leaves you\n-in a state that may be hard to back out of in the case of a conflict.\n-\n-If any of the remote changes overlap with local uncommitted changes,\n-the merge will be automatically canceled and the work tree untouched.\n-It is generally best to get any local changes in working order before\n-pulling or stash them away with linkgit:git-stash[1].\n+If there's a merge conflict during the merge or rebase that you don't\n+want to handle, you can safely abort it with `git merge --abort` or `git\n+--rebase abort`.\n \n OPTIONS\n -------\n-- \ngitgitgadget\n"},{"id":"528826","messageId":"0149FFFE-608D-48F0-A80F-D2B76D943F9B@gmail.com","threadId":"64194","inReplyTo":"pull.1976.v3.git.1760534011.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 0/4] doc: git-pull: clarify DESCRIPTION section","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-10-15T16:56:51Z","receivedAt":"2025-10-15T16:57:03Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"\n> Le 15 oct. 2025 à 09:13, Julia Evans via GitGitGadget a écrit :\n> \n> I got feedback from 15 Git users on the current git pull man page, using\n> this tool: https://text-feedback.wizardzines.com/git-pull.\n> \n> My goals here are to be clear about the relationship between git pull and\n> fetch/merge/rebase etc, make sure users know the current default for git\n> pull (--ff-only) since some folks still remember the old default, and to\n> help users quickly figure out what command they need to run to\n> merge/rebase/squash/etc.\n> \n> I've taken a pretty aggressive approach because I think it's possible to\n> have a pretty short and focused DESCRIPTION section here while keeping the\n> most important info. Open to hearing that I've removed too much.\n> \n> This references the UPSTREAM BRANCHES section from\n> https://lore.kernel.org/git/0ec629d4037bf5d1ccc248ca1bbd87ccc08119a3.1757703309.git.gitgitgadget@gmail.com/\n> , so if that isn't merged I'll need to revisit the approach here.\n> \n> changes in v2:\n> \n> * Add \"(excluding merge options)\" to clarify which options are passed to\n> git fetch (from Chris's review)\n> * Say that git pull will by default merge the upstream branch. (from\n> Chris's review)\n> * Add some links to the UPSTREAM BRANCHES section, and to the \n> section in git fetch, to make it easier to navigate in the HTML version\n> of the docs at least. The situation where we repeat the part\n> in git fetch is weird but I don't have a better idea for how to handle it\n> right now. The UPSTREAM BRANCHES links are currently failing the\n> documentation tests, but should pass once the patch series that adds that\n> is merged. (from Ben's review)\n> \n> changes in v3:\n> \n> Change \"fails if the local branch has diverged\" to say \"remote branch has\n> diverged\", from Junio's review.\n> \n> I did not come up with a better idea for a word to use than \"integrate\" so\n> left that alone.\n\nI’m happy with this version ; anyone else ?"},{"id":"528831","messageId":"xmqqms5rucl7.fsf@gitster.g","threadId":"64194","inReplyTo":"pull.1976.v3.git.1760534011.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 0/4] doc: git-pull: clarify DESCRIPTION section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-15T20:36:20Z","receivedAt":"2025-10-15T20:36:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" writes:\n\n> I got feedback from 15 Git users on the current git pull man page, using\n> this tool: https://text-feedback.wizardzines.com/git-pull.\n>\n> My goals here are to be clear about the relationship between git pull and\n> fetch/merge/rebase etc, make sure users know the current default for git\n> pull (--ff-only) since some folks still remember the old default, and to\n> help users quickly figure out what command they need to run to\n> merge/rebase/squash/etc.\n>\n> I've taken a pretty aggressive approach because I think it's possible to\n> have a pretty short and focused DESCRIPTION section here while keeping the\n> most important info. Open to hearing that I've removed too much.\n>\n> This references the UPSTREAM BRANCHES section from\n> https://lore.kernel.org/git/0ec629d4037bf5d1ccc248ca1bbd87ccc08119a3.1757703309.git.gitgitgadget@gmail.com/\n> , so if that isn't merged I'll need to revisit the approach here.\n\nLooking good. I have no more comments on this series at this\nmoment.\n\nShall I mark the topic for 'next' now?\n\nThanks.\n"}]}