{"thread":{"id":"59046","subject":"[PATCH 0/5] Documentation: updates and a correction around 'ORIG_HEAD'","startedAt":"2023-01-07T19:39:26Z","lastAt":"2023-01-13T18:03:48Z","messageCount":20,"participants":["Philippe Blain via GitGitGadget","Junio C Hamano","Philippe Blain","Phillip Wood"],"isPatch":true,"patchVersion":1,"patchTotal":5},"messages":[{"id":"469886","messageId":"pull.1456.git.1673120359.gitgitgadget@gmail.com","threadId":"59046","inReplyTo":null,"subject":"[PATCH 0/5] Documentation: updates and a correction around 'ORIG_HEAD'","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-07T19:39:14Z","receivedAt":"2023-01-07T19:39:26Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"This series' initial motivation was to clear up a confusion that arose in\n[1] where it was noticed that 'ORIG_HEAD' is not guaranteed to point to the\noriginal branch tip at the end of the rebase if 'git reset' is used during\nthe rebase.\n\nPatch 5/5 adds a note to 'git rebase's documentation to make that explicit.\nWhen taking a look at the existing documentation mentioning 'ORIG_HEAD', I\nalso found an error in an example (patch 1/5), other small inconsistencies\n(patch 2-3/5), and a potential improvement (patch 4/5).\n\nCheers,\n\nPhilippe.\n\n[1]\nhttps://lore.kernel.org/git/1b2b8e98-5506-a1e6-6059-a967757b3bb8@gmail.com/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0\n\nPhilippe Blain (5):\n git-cherry-pick.txt: do not use 'ORIG_HEAD' in example\n git-reset.txt: mention 'ORIG_HEAD' in the Description\n git-merge.txt: mention 'ORIG_HEAD' in the Description\n revisions.txt: be explicit about commands writing 'ORIG_HEAD'\n git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten\n\n Documentation/git-cherry-pick.txt | 2 +-\n Documentation/git-merge.txt | 3 ++-\n Documentation/git-rebase.txt | 7 +++++++\n Documentation/git-reset.txt | 3 ++-\n Documentation/revisions.txt | 3 ++-\n 5 files changed, 14 insertions(+), 4 deletions(-)\n\n\nbase-commit: 4dbebc36b0893f5094668ddea077d0e235560b16\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1456%2Fphil-blain%2Fdoc-orig-head-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1456/phil-blain/doc-orig-head-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1456\n-- \ngitgitgadget\n"},{"id":"469887","messageId":"74b2d5a9144e4893311d9acfb0b5e8268da6f0f0.1673120359.git.gitgitgadget@gmail.com","threadId":"59046","inReplyTo":"pull.1456.git.1673120359.gitgitgadget@gmail.com","subject":"[PATCH 1/5] git-cherry-pick.txt: do not use 'ORIG_HEAD' in example","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-07T19:39:15Z","receivedAt":"2023-01-07T19:39:29Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nCommit 67ac1e1d57 (cherry-pick/revert: add support for\n-X/--strategy-option, 2010-12-10) added an example to the documentation\nof 'git cherry-pick'. This example mentions how to abort a failed\ncherry-pick and retry with an additional merge strategy option.\n\nThe command used in the example to abort the cherry-pick is 'git reset\n--merge ORIG_HEAD', but cherry-pick does not write 'ORIG_HEAD' before\nstarting its operation. So this command would checkout a commit\nunrelated to what was at HEAD when the user invoked cherry-pick.\n\nUse 'git cherry-pick --abort' instead.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/git-cherry-pick.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt\nindex 1e8ac9df602..fdcad3d2006 100644\n--- a/Documentation/git-cherry-pick.txt\n+++ b/Documentation/git-cherry-pick.txt\n@@ -219,7 +219,7 @@ again, this time exercising more care about matching up context lines.\n ------------\n $ git cherry-pick topic^ <1>\n $ git diff <2>\n-$ git reset --merge ORIG_HEAD <3>\n+$ git cherry-pick --abort <3>\n $ git cherry-pick -Xpatience topic^ <4>\n ------------\n <1> apply the change that would be shown by `git show topic^`.\n-- \ngitgitgadget\n\n"},{"id":"469888","messageId":"f25c71fd4c31b5c08974b275b3ab23b6c8048fce.1673120359.git.gitgitgadget@gmail.com","threadId":"59046","inReplyTo":"pull.1456.git.1673120359.gitgitgadget@gmail.com","subject":"[PATCH 2/5] git-reset.txt: mention 'ORIG_HEAD' in the Description","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-07T19:39:16Z","receivedAt":"2023-01-07T19:39:31Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nThe fact that 'git reset' writes 'ORIG_HEAD' before changing HEAD is\nmentioned in an example, but is missing from the 'Description' section.\n\nMention it in the discussion of the \"'git reset' [] []\"\nform of the command.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/git-reset.txt | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt\nindex 01cb4c9b9c5..79ad5643eed 100644\n--- a/Documentation/git-reset.txt\n+++ b/Documentation/git-reset.txt\n@@ -49,7 +49,8 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n 'git reset' [] []::\n \tThis form resets the current branch head to `` and\n \tpossibly updates the index (resetting it to the tree of ``) and\n-\tthe working tree depending on ``. If `` is omitted,\n+\tthe working tree depending on ``. Before the operation, `ORIG_HEAD`\n+\tis set to the tip of the current branch. If `` is omitted,\n \tdefaults to `--mixed`. The `` must be one of the following:\n +\n --\n-- \ngitgitgadget\n\n"},{"id":"469889","messageId":"e488ad3ce1d2e227f5440fc04d0f6aeb6347a82a.1673120359.git.gitgitgadget@gmail.com","threadId":"59046","inReplyTo":"pull.1456.git.1673120359.gitgitgadget@gmail.com","subject":"[PATCH 3/5] git-merge.txt: mention 'ORIG_HEAD' in the Description","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-07T19:39:17Z","receivedAt":"2023-01-07T19:39:33Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nThe fact that 'git merge' writes 'ORIG_HEAD' before performing the merge\nis missing from the documentation of the command.\n\nMention it in the 'Description' section.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/git-merge.txt | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 2d6a1391c89..0aeff572a59 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -37,7 +37,8 @@ Then \"`git merge topic`\" will replay the changes made on the\n `topic` branch since it diverged from `master` (i.e., `E`) until\n its current commit (`C`) on top of `master`, and record the result\n in a new commit along with the names of the two parent commits and\n-a log message from the user describing the changes.\n+a log message from the user describing the changes. Before the operation,\n+`ORIG_HEAD` is set to the tip of the current branch (`C`).\n \n ------------\n \t A---B---C topic\n-- \ngitgitgadget\n\n"},{"id":"469890","messageId":"302b789a4869c2aa8a0de2f71a2725c6c567685f.1673120359.git.gitgitgadget@gmail.com","threadId":"59046","inReplyTo":"pull.1456.git.1673120359.gitgitgadget@gmail.com","subject":"[PATCH 4/5] revisions.txt: be explicit about commands writing 'ORIG_HEAD'","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-07T19:39:18Z","receivedAt":"2023-01-07T19:39:35Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nWhen mentioning 'ORIG_HEAD', be explicit about which command write that\npseudo-ref, namely 'git am', 'git merge', 'git rebase' and 'git reset'.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/revisions.txt | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 0d2e55d7819..9aa58052bc7 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -49,7 +49,8 @@ characters and to avoid word splitting.\n `FETCH_HEAD` records the branch which you fetched from a remote repository\n with your last `git fetch` invocation.\n `ORIG_HEAD` is created by commands that move your `HEAD` in a drastic\n-way, to record the position of the `HEAD` before their operation, so that\n+way (`git am`, `git merge`, `git rebase`, `git reset`),\n+to record the position of the `HEAD` before their operation, so that\n you can easily change the tip of the branch back to the state before you ran\n them.\n `MERGE_HEAD` records the commit(s) which you are merging into your branch\n-- \ngitgitgadget\n\n"},{"id":"469891","messageId":"9ef427a9a2adfb6a47d13103f00a64df96725560.1673120359.git.gitgitgadget@gmail.com","threadId":"59046","inReplyTo":"pull.1456.git.1673120359.gitgitgadget@gmail.com","subject":"[PATCH 5/5] git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-07T19:39:19Z","receivedAt":"2023-01-07T19:39:36Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\n'ORIG_HEAD' is written at the start of the rebase, but is not guaranteed\nto still point to the original branch tip at the end of the rebase.\n\nIndeed, using other commands that write 'ORIG_HEAD' during the rebase,\nlike splitting a commit using 'git reset HEAD^', will lead to 'ORIG_HEAD'\nbeing overwritten.\n\nAdd a note about that in the 'Description' section, and mention the more\nrobust alternative of using the branch's reflog.\n\nReported-by: Erik Cervin Edin \nSigned-off-by: Philippe Blain \n---\n Documentation/git-rebase.txt | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex f9675bd24e6..d811c1cf443 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -38,6 +38,13 @@ The current branch is reset to `` or `` if the\n `git reset --hard ` (or ``). `ORIG_HEAD` is set\n to point at the tip of the branch before the reset.\n \n+[NOTE]\n+`ORIG_HEAD` is not guaranteed to still point to the previous branch tip\n+at the end of the rebase if other commands that write that pseudo-ref\n+(e.g. `git reset`) are used during the rebase. The previous branch tip,\n+however, is accessible using the reflog of the current branch\n+(i.e. `@{1}`, see linkgit:gitrevisions[7]).\n+\n The commits that were previously saved into the temporary area are\n then reapplied to the current branch, one by one, in order. Note that\n any commits in `HEAD` which introduce the same textual changes as a commit\n-- \ngitgitgadget\n"},{"id":"469898","messageId":"xmqqh6x1232e.fsf@gitster.g","threadId":"59046","inReplyTo":"74b2d5a9144e4893311d9acfb0b5e8268da6f0f0.1673120359.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/5] git-cherry-pick.txt: do not use 'ORIG_HEAD' in example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-01-08T02:05:45Z","receivedAt":"2023-01-08T02:05:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philippe Blain via GitGitGadget\" writes:\n\n> The command used in the example to abort the cherry-pick is 'git reset\n> --merge ORIG_HEAD', but cherry-pick does not write 'ORIG_HEAD' before\n> starting its operation.\n\nSorry, but I am confused. Doesn't <1> update ORIG_HEAD used by <3>?\n\n> $ git cherry-pick topic^ <1>\n> $ git diff <2>\n> -$ git reset --merge ORIG_HEAD <3>\n> +$ git cherry-pick --abort <3>\n> $ git cherry-pick -Xpatience topic^ <4>\n> ------------\n> <1> apply the change that would be shown by `git show topic^`.\n\n"},{"id":"469899","messageId":"xmqqcz7p22x5.fsf@gitster.g","threadId":"59046","inReplyTo":"302b789a4869c2aa8a0de2f71a2725c6c567685f.1673120359.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 4/5] revisions.txt: be explicit about commands writing 'ORIG_HEAD'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-01-08T02:08:54Z","receivedAt":"2023-01-08T02:08:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philippe Blain via GitGitGadget\" writes:\n\n> -way, to record the position of the `HEAD` before their operation, so that\n> +way (`git am`, `git merge`, `git rebase`, `git reset`),\n\nLet's not commit that these four will forever stay to be the\ncommands that uses ORIG_HEAD. Perhaps \"(e.g. `git am`, ...)\"?\n\n> +to record the position of the `HEAD` before their operation, so that\n\n"},{"id":"469900","messageId":"xmqq4jt122k2.fsf@gitster.g","threadId":"59046","inReplyTo":"9ef427a9a2adfb6a47d13103f00a64df96725560.1673120359.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 5/5] git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-01-08T02:16:45Z","receivedAt":"2023-01-08T02:16:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philippe Blain via GitGitGadget\" writes:\n\n> From: Philippe Blain \n>\n> 'ORIG_HEAD' is written at the start of the rebase, but is not guaranteed\n> to still point to the original branch tip at the end of the rebase.\n>\n> Indeed, using other commands that write 'ORIG_HEAD' during the rebase,\n> like splitting a commit using 'git reset HEAD^', will lead to 'ORIG_HEAD'\n> being overwritten.\n\nIs that a news? If a user does \"reset\", the user is asking that\nHEAD is changed and the old state kept in ORIG_HEAD at the same\ntime, so while it is not wrong per-se to say that user can clobber\nORIG_HEAD after rebase sets it first, it is pretty much expected,\nno?\n\nWhat would be unexpected is if \"rebase\" overwrote ORIG_HEAD after\nuser did all these other things while it gave control back and then\nit took control back, and it would be worth documenting.\n\nHaving said that, I do not mind documenting this. I am not sure \"is\nnot guaranteed\" is a good way to phrase what happens, though.\n\n> +[NOTE]\n> +`ORIG_HEAD` is not guaranteed to still point to the previous branch tip\n> +at the end of the rebase if other commands that write that pseudo-ref\n> +(e.g. `git reset`) are used during the rebase. The previous branch tip,\n> +however, is accessible using the reflog of the current branch\n> +(i.e. `@{1}`, see linkgit:gitrevisions[7]).\n\n `ORIG_HEAD` is set to point at the tip of the previous branch\n when `rebase` begins, but the user can run commands (e.g. \"git\n reset\") that overwrites `ORIG_HEAD` while `rebase` gives control\n to the user (e.g. while asking to resolve conflict).\n\nIt is excellent to mention reflog, which is very much an upward\ncompatible replacement of ORIG_HEAD.\n\nThanks.\n"},{"id":"469974","messageId":"4525699c-eed5-4da6-b469-b73b87525b23@gmail.com","threadId":"59046","inReplyTo":"xmqqh6x1232e.fsf@gitster.g","subject":"Re: [PATCH 1/5] git-cherry-pick.txt: do not use 'ORIG_HEAD' in example","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2023-01-09T13:56:58Z","receivedAt":"2023-01-09T13:57:38Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"\nHi Junio,\n\nLe 2023-01-07 à 21:05, Junio C Hamano a écrit :\n> \"Philippe Blain via GitGitGadget\" writes:\n> \n>> The command used in the example to abort the cherry-pick is 'git reset\n>> --merge ORIG_HEAD', but cherry-pick does not write 'ORIG_HEAD' before\n>> starting its operation.\n> \n> Sorry, but I am confused. Doesn't <1> update ORIG_HEAD used by <3>?\n> \n>> $ git cherry-pick topic^ <1>\n>> $ git diff <2>\n>> -$ git reset --merge ORIG_HEAD <3>\n>> +$ git cherry-pick --abort <3>\n>> $ git cherry-pick -Xpatience topic^ <4>\n>> ------------\n>> <1> apply the change that would be shown by `git show topic^`.\n> \n\nNo, as far as I was able to test and from my reading of the code,\ncherry-pick does not write ORIG_HEAD.\n\nHere is a little script that demonstrates this:\n\n```\n#!/bin/sh\n\nrm -rf test\ngit -c init.defaultBranch=master init test\n(\n\ncd test\necho hello>file\ngit add file\ngit commit -m initial\ngit branch other\necho two>>file\ngit commit -am two\ngit checkout other\necho three >>file\ngit commit -am three\ngit checkout master\n# This writes ORIG_HEAD as 'two'\ngit reset HEAD^\ngit commit -a -m two-redone\n# This does not\ngit cherry-pick other\n# This shows ORIG_HEAD written by reset:\necho ORIG_HEAD is:\ngit log --oneline -1 ORIG_HEAD\n# Whereas HEAD is 'two-redone':\necho HEAD is:\ngit log --oneline -1 HEAD\n)\n```\n\nLooking at the code, 'git grep -p ORIG_HEAD \\*.c'\nreveals the only builtin that write ORIG_HEAD are \nam, merge, rebase and reset, and the only library code\nthat involves ORIG_HEAD is reset.c::reset_head.\n\nMoreover, 'git grep -p [^a-z_]reset_head \\*.c'\nreveals that the only non-builtin user of reset.c::reset_head\nis sequencer.c::create_autostash, in which the RESET_ORIG_HEAD \nflag of 'struct reset_head_opts ropts' is not set.\n\nThat is what convinced me that cherry-pick does not write ORIG_HEAD.\n\nThanks,\n\nPhilippe.\n"},{"id":"469975","messageId":"530a9dc9-dc16-fe26-954c-27daabf9e9bd@gmail.com","threadId":"59046","inReplyTo":"xmqqcz7p22x5.fsf@gitster.g","subject":"Re: [PATCH 4/5] revisions.txt: be explicit about commands writing 'ORIG_HEAD'","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2023-01-09T14:00:11Z","receivedAt":"2023-01-09T14:02:06Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Junio,\n\nLe 2023-01-07 à 21:08, Junio C Hamano a écrit :\n> \"Philippe Blain via GitGitGadget\" writes:\n> \n>> -way, to record the position of the `HEAD` before their operation, so that\n>> +way (`git am`, `git merge`, `git rebase`, `git reset`),\n> \n> Let's not commit that these four will forever stay to be the\n> commands that uses ORIG_HEAD. Perhaps \"(e.g. `git am`, ...)\"?\n> \n>> +to record the position of the `HEAD` before their operation, so that\n> \n\nI think I prefer being explicit in the documentation. It's easier for a user\nwanting to learn which commands write that pseudo-ref to have them all listed\nat the same place. If other commands learn to write it, we can update the list \nhere.\n\nThat said, I can live with that patch being tweaked in the next iteration if people\nfeel strongly about an explicit list.\n\nPhilippe.\n"},{"id":"469995","messageId":"85da5311-bef6-88d9-850d-888d874f6988@gmail.com","threadId":"59046","inReplyTo":"xmqq4jt122k2.fsf@gitster.g","subject":"Re: [PATCH 5/5] git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2023-01-09T18:22:10Z","receivedAt":"2023-01-09T18:24:11Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Junio,\n\nLe 2023-01-07 à 21:16, Junio C Hamano a écrit :\n> \"Philippe Blain via GitGitGadget\" writes:\n> \n>> From: Philippe Blain \n>>\n>> 'ORIG_HEAD' is written at the start of the rebase, but is not guaranteed\n>> to still point to the original branch tip at the end of the rebase.\n>>\n>> Indeed, using other commands that write 'ORIG_HEAD' during the rebase,\n>> like splitting a commit using 'git reset HEAD^', will lead to 'ORIG_HEAD'\n>> being overwritten.\n> \n> Is that a news? If a user does \"reset\", the user is asking that\n> HEAD is changed and the old state kept in ORIG_HEAD at the same\n> time, so while it is not wrong per-se to say that user can clobber\n> ORIG_HEAD after rebase sets it first, it is pretty much expected,\n> no?\n\nI forgot to add a link to the mailing list thread and just added a Reported-by\ntrailer here, but it was not expected by at least 2 users (including me) [1].\n\n[1] https://lore.kernel.org/git/28ebf03b-e8bb-3769-556b-c9db17e43dbb@gmail.com/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0\n\nI think of 'git reset HEAD^' during a rebase, to split a existing commit,\nas rebase-related operation (it could almost be a different instruction in the TODO\nlist), and so my expectation was that ORIG_HEAD at the end of the rebase would\nnot be changed by what I did during the rebase.\n\nBut I can see how it would be confusing for people that would expect ORIG_HEAD\nto point to the pre-reset HEAD, and so I just thought I'd point that out in the \ndoc to avoid potential future confusion.\n\n> \n> What would be unexpected is if \"rebase\" overwrote ORIG_HEAD after\n> user did all these other things while it gave control back and then\n> it took control back, and it would be worth documenting.\n> \n> Having said that, I do not mind documenting this. I am not sure \"is\n> not guaranteed\" is a good way to phrase what happens, though.\n\nI use that phrasing because the 'gitrevisions' entry on 'ORIG_HEAD' says:\n\n\n `ORIG_HEAD` is created by commands that move your `HEAD` in a drastic\n way ([...]),\n to record the position of the `HEAD` before their operation, so that\n you can easily change the tip of the branch back to the state before you ran\n them.\n\nso it might be read to mean that 'ORIG_HEAD' always points to the pre-operation\nstate. I'm open to other wording, though.\n\n> \n>> +[NOTE]\n>> +`ORIG_HEAD` is not guaranteed to still point to the previous branch tip\n>> +at the end of the rebase if other commands that write that pseudo-ref\n>> +(e.g. `git reset`) are used during the rebase. The previous branch tip,\n>> +however, is accessible using the reflog of the current branch\n>> +(i.e. `@{1}`, see linkgit:gitrevisions[7]).\n> \n> `ORIG_HEAD` is set to point at the tip of the previous branch\n> when `rebase` begins, but the user can run commands (e.g. \"git\n> reset\") that overwrites `ORIG_HEAD` while `rebase` gives control\n> to the user (e.g. while asking to resolve conflict).\n> \n> It is excellent to mention reflog, which is very much an upward\n> compatible replacement of ORIG_HEAD.\n> \n> Thanks.\n> \n\nThanks, I'll consider that wording for v2.\n\nCheers,\n\nPhilippe.\n"},{"id":"470063","messageId":"74b2d5a9144e4893311d9acfb0b5e8268da6f0f0.1673356522.git.gitgitgadget@gmail.com","threadId":"59046","inReplyTo":"pull.1456.v2.git.1673356521.gitgitgadget@gmail.com","subject":"[PATCH v2 1/5] git-cherry-pick.txt: do not use 'ORIG_HEAD' in example","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-10T13:15:17Z","receivedAt":"2023-01-10T13:15:53Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nCommit 67ac1e1d57 (cherry-pick/revert: add support for\n-X/--strategy-option, 2010-12-10) added an example to the documentation\nof 'git cherry-pick'. This example mentions how to abort a failed\ncherry-pick and retry with an additional merge strategy option.\n\nThe command used in the example to abort the cherry-pick is 'git reset\n--merge ORIG_HEAD', but cherry-pick does not write 'ORIG_HEAD' before\nstarting its operation. So this command would checkout a commit\nunrelated to what was at HEAD when the user invoked cherry-pick.\n\nUse 'git cherry-pick --abort' instead.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/git-cherry-pick.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt\nindex 1e8ac9df602..fdcad3d2006 100644\n--- a/Documentation/git-cherry-pick.txt\n+++ b/Documentation/git-cherry-pick.txt\n@@ -219,7 +219,7 @@ again, this time exercising more care about matching up context lines.\n ------------\n $ git cherry-pick topic^ <1>\n $ git diff <2>\n-$ git reset --merge ORIG_HEAD <3>\n+$ git cherry-pick --abort <3>\n $ git cherry-pick -Xpatience topic^ <4>\n ------------\n <1> apply the change that would be shown by `git show topic^`.\n-- \ngitgitgadget\n\n"},{"id":"470064","messageId":"f25c71fd4c31b5c08974b275b3ab23b6c8048fce.1673356522.git.gitgitgadget@gmail.com","threadId":"59046","inReplyTo":"pull.1456.v2.git.1673356521.gitgitgadget@gmail.com","subject":"[PATCH v2 2/5] git-reset.txt: mention 'ORIG_HEAD' in the Description","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-10T13:15:18Z","receivedAt":"2023-01-10T13:16:02Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nThe fact that 'git reset' writes 'ORIG_HEAD' before changing HEAD is\nmentioned in an example, but is missing from the 'Description' section.\n\nMention it in the discussion of the \"'git reset' [] []\"\nform of the command.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/git-reset.txt | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt\nindex 01cb4c9b9c5..79ad5643eed 100644\n--- a/Documentation/git-reset.txt\n+++ b/Documentation/git-reset.txt\n@@ -49,7 +49,8 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n 'git reset' [] []::\n \tThis form resets the current branch head to `` and\n \tpossibly updates the index (resetting it to the tree of ``) and\n-\tthe working tree depending on ``. If `` is omitted,\n+\tthe working tree depending on ``. Before the operation, `ORIG_HEAD`\n+\tis set to the tip of the current branch. If `` is omitted,\n \tdefaults to `--mixed`. The `` must be one of the following:\n +\n --\n-- \ngitgitgadget\n\n"},{"id":"470065","messageId":"e488ad3ce1d2e227f5440fc04d0f6aeb6347a82a.1673356522.git.gitgitgadget@gmail.com","threadId":"59046","inReplyTo":"pull.1456.v2.git.1673356521.gitgitgadget@gmail.com","subject":"[PATCH v2 3/5] git-merge.txt: mention 'ORIG_HEAD' in the Description","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-10T13:15:19Z","receivedAt":"2023-01-10T13:16:02Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nThe fact that 'git merge' writes 'ORIG_HEAD' before performing the merge\nis missing from the documentation of the command.\n\nMention it in the 'Description' section.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/git-merge.txt | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 2d6a1391c89..0aeff572a59 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -37,7 +37,8 @@ Then \"`git merge topic`\" will replay the changes made on the\n `topic` branch since it diverged from `master` (i.e., `E`) until\n its current commit (`C`) on top of `master`, and record the result\n in a new commit along with the names of the two parent commits and\n-a log message from the user describing the changes.\n+a log message from the user describing the changes. Before the operation,\n+`ORIG_HEAD` is set to the tip of the current branch (`C`).\n \n ------------\n \t A---B---C topic\n-- \ngitgitgadget\n\n"},{"id":"470066","messageId":"pull.1456.v2.git.1673356521.gitgitgadget@gmail.com","threadId":"59046","inReplyTo":"pull.1456.git.1673120359.gitgitgadget@gmail.com","subject":"[PATCH v2 0/5] Documentation: updates and a correction around 'ORIG_HEAD'","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-10T13:15:16Z","receivedAt":"2023-01-10T13:16:02Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":" * added a link to the mailing list thread in the commit message of 5/5.\n\nv1: Documentation: updates and a correction around 'ORIG_HEAD'\n\nThis series' initial motivation was to clear up a confusion that arose in\n[1] where it was noticed that 'ORIG_HEAD' is not guaranteed to point to the\noriginal branch tip at the end of the rebase if 'git reset' is used during\nthe rebase.\n\nPatch 5/5 adds a note to 'git rebase's documentation to make that explicit.\nWhen taking a look at the existing documentation mentioning 'ORIG_HEAD', I\nalso found an error in an example (patch 1/5), other small inconsistencies\n(patch 2-3/5), and a potential improvement (patch 4/5).\n\nCheers,\n\nPhilippe.\n\n[1]\nhttps://lore.kernel.org/git/1b2b8e98-5506-a1e6-6059-a967757b3bb8@gmail.com/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0\n\nPhilippe Blain (5):\n git-cherry-pick.txt: do not use 'ORIG_HEAD' in example\n git-reset.txt: mention 'ORIG_HEAD' in the Description\n git-merge.txt: mention 'ORIG_HEAD' in the Description\n revisions.txt: be explicit about commands writing 'ORIG_HEAD'\n git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten\n\n Documentation/git-cherry-pick.txt | 2 +-\n Documentation/git-merge.txt | 3 ++-\n Documentation/git-rebase.txt | 7 +++++++\n Documentation/git-reset.txt | 3 ++-\n Documentation/revisions.txt | 3 ++-\n 5 files changed, 14 insertions(+), 4 deletions(-)\n\n\nbase-commit: 4dbebc36b0893f5094668ddea077d0e235560b16\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1456%2Fphil-blain%2Fdoc-orig-head-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1456/phil-blain/doc-orig-head-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/1456\n\nRange-diff vs v1:\n\n 1: 74b2d5a9144 = 1: 74b2d5a9144 git-cherry-pick.txt: do not use 'ORIG_HEAD' in example\n 2: f25c71fd4c3 = 2: f25c71fd4c3 git-reset.txt: mention 'ORIG_HEAD' in the Description\n 3: e488ad3ce1d = 3: e488ad3ce1d git-merge.txt: mention 'ORIG_HEAD' in the Description\n 4: 302b789a486 = 4: 302b789a486 revisions.txt: be explicit about commands writing 'ORIG_HEAD'\n 5: 9ef427a9a2a ! 5: 7eed8f35376 git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten\n @@ Commit message\n \n Indeed, using other commands that write 'ORIG_HEAD' during the rebase,\n like splitting a commit using 'git reset HEAD^', will lead to 'ORIG_HEAD'\n - being overwritten.\n + being overwritten. This causes confusion for some users [1].\n \n Add a note about that in the 'Description' section, and mention the more\n robust alternative of using the branch's reflog.\n \n + [1] https://lore.kernel.org/git/28ebf03b-e8bb-3769-556b-c9db17e43dbb@gmail.com/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0\n +\n Reported-by: Erik Cervin Edin \n Signed-off-by: Philippe Blain \n \n\n-- \ngitgitgadget\n"},{"id":"470067","messageId":"302b789a4869c2aa8a0de2f71a2725c6c567685f.1673356522.git.gitgitgadget@gmail.com","threadId":"59046","inReplyTo":"pull.1456.v2.git.1673356521.gitgitgadget@gmail.com","subject":"[PATCH v2 4/5] revisions.txt: be explicit about commands writing 'ORIG_HEAD'","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-10T13:15:20Z","receivedAt":"2023-01-10T13:16:06Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nWhen mentioning 'ORIG_HEAD', be explicit about which command write that\npseudo-ref, namely 'git am', 'git merge', 'git rebase' and 'git reset'.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/revisions.txt | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 0d2e55d7819..9aa58052bc7 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -49,7 +49,8 @@ characters and to avoid word splitting.\n `FETCH_HEAD` records the branch which you fetched from a remote repository\n with your last `git fetch` invocation.\n `ORIG_HEAD` is created by commands that move your `HEAD` in a drastic\n-way, to record the position of the `HEAD` before their operation, so that\n+way (`git am`, `git merge`, `git rebase`, `git reset`),\n+to record the position of the `HEAD` before their operation, so that\n you can easily change the tip of the branch back to the state before you ran\n them.\n `MERGE_HEAD` records the commit(s) which you are merging into your branch\n-- \ngitgitgadget\n\n"},{"id":"470068","messageId":"7eed8f353764774cc7335c51338db6cba14675aa.1673356522.git.gitgitgadget@gmail.com","threadId":"59046","inReplyTo":"pull.1456.v2.git.1673356521.gitgitgadget@gmail.com","subject":"[PATCH v2 5/5] git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-10T13:15:21Z","receivedAt":"2023-01-10T13:16:13Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\n'ORIG_HEAD' is written at the start of the rebase, but is not guaranteed\nto still point to the original branch tip at the end of the rebase.\n\nIndeed, using other commands that write 'ORIG_HEAD' during the rebase,\nlike splitting a commit using 'git reset HEAD^', will lead to 'ORIG_HEAD'\nbeing overwritten. This causes confusion for some users [1].\n\nAdd a note about that in the 'Description' section, and mention the more\nrobust alternative of using the branch's reflog.\n\n[1] https://lore.kernel.org/git/28ebf03b-e8bb-3769-556b-c9db17e43dbb@gmail.com/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0\n\nReported-by: Erik Cervin Edin \nSigned-off-by: Philippe Blain \n---\n Documentation/git-rebase.txt | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex f9675bd24e6..d811c1cf443 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -38,6 +38,13 @@ The current branch is reset to `` or `` if the\n `git reset --hard ` (or ``). `ORIG_HEAD` is set\n to point at the tip of the branch before the reset.\n \n+[NOTE]\n+`ORIG_HEAD` is not guaranteed to still point to the previous branch tip\n+at the end of the rebase if other commands that write that pseudo-ref\n+(e.g. `git reset`) are used during the rebase. The previous branch tip,\n+however, is accessible using the reflog of the current branch\n+(i.e. `@{1}`, see linkgit:gitrevisions[7]).\n+\n The commits that were previously saved into the temporary area are\n then reapplied to the current branch, one by one, in order. Note that\n any commits in `HEAD` which introduce the same textual changes as a commit\n-- \ngitgitgadget\n"},{"id":"470077","messageId":"ba20039c-19a3-96da-c938-89af67bca791@dunelm.org.uk","threadId":"59046","inReplyTo":"pull.1456.v2.git.1673356521.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 0/5] Documentation: updates and a correction around 'ORIG_HEAD'","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2023-01-10T20:06:40Z","receivedAt":"2023-01-10T20:07:19Z","isPatch":true,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"Hi Philippe\n\nOn 10/01/2023 13:15, Philippe Blain via GitGitGadget wrote:\n> * added a link to the mailing list thread in the commit message of 5/5.\n> \n> v1: Documentation: updates and a correction around 'ORIG_HEAD'\n> \n> This series' initial motivation was to clear up a confusion that arose in\n> [1] where it was noticed that 'ORIG_HEAD' is not guaranteed to point to the\n> original branch tip at the end of the rebase if 'git reset' is used during\n> the rebase.\n> \n> Patch 5/5 adds a note to 'git rebase's documentation to make that explicit.\n> When taking a look at the existing documentation mentioning 'ORIG_HEAD', I\n> also found an error in an example (patch 1/5), other small inconsistencies\n> (patch 2-3/5), and a potential improvement (patch 4/5).\n\nThanks for doing this, I think the adding a note to the rebase \ndocumentation is a good idea given the confusion that's been reported. \nThe patches all look great to me apart from patch 4 where I share \nJunio's concerns about the readability and maintenance burden of the \nlist of commands. I was surprised to learn that merge also sets \nORIG_HEAD, thanks for being so thorough.\n\nBest Wishes\n\nPhillip\n\n> Cheers,\n> \n> Philippe.\n> \n> [1]\n> https://lore.kernel.org/git/1b2b8e98-5506-a1e6-6059-a967757b3bb8@gmail.com/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0\n> \n> Philippe Blain (5):\n> git-cherry-pick.txt: do not use 'ORIG_HEAD' in example\n> git-reset.txt: mention 'ORIG_HEAD' in the Description\n> git-merge.txt: mention 'ORIG_HEAD' in the Description\n> revisions.txt: be explicit about commands writing 'ORIG_HEAD'\n> git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten\n> \n> Documentation/git-cherry-pick.txt | 2 +-\n> Documentation/git-merge.txt | 3 ++-\n> Documentation/git-rebase.txt | 7 +++++++\n> Documentation/git-reset.txt | 3 ++-\n> Documentation/revisions.txt | 3 ++-\n> 5 files changed, 14 insertions(+), 4 deletions(-)\n> \n> \n> base-commit: 4dbebc36b0893f5094668ddea077d0e235560b16\n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1456%2Fphil-blain%2Fdoc-orig-head-v2\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1456/phil-blain/doc-orig-head-v2\n> Pull-Request: https://github.com/gitgitgadget/git/pull/1456\n> \n> Range-diff vs v1:\n> \n> 1: 74b2d5a9144 = 1: 74b2d5a9144 git-cherry-pick.txt: do not use 'ORIG_HEAD' in example\n> 2: f25c71fd4c3 = 2: f25c71fd4c3 git-reset.txt: mention 'ORIG_HEAD' in the Description\n> 3: e488ad3ce1d = 3: e488ad3ce1d git-merge.txt: mention 'ORIG_HEAD' in the Description\n> 4: 302b789a486 = 4: 302b789a486 revisions.txt: be explicit about commands writing 'ORIG_HEAD'\n> 5: 9ef427a9a2a ! 5: 7eed8f35376 git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten\n> @@ Commit message\n> \n> Indeed, using other commands that write 'ORIG_HEAD' during the rebase,\n> like splitting a commit using 'git reset HEAD^', will lead to 'ORIG_HEAD'\n> - being overwritten.\n> + being overwritten. This causes confusion for some users [1].\n> \n> Add a note about that in the 'Description' section, and mention the more\n> robust alternative of using the branch's reflog.\n> \n> + [1] https://lore.kernel.org/git/28ebf03b-e8bb-3769-556b-c9db17e43dbb@gmail.com/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0\n> +\n> Reported-by: Erik Cervin Edin \n> Signed-off-by: Philippe Blain \n> \n> \n"},{"id":"470294","messageId":"xmqqk01q48t7.fsf@gitster.g","threadId":"59046","inReplyTo":"ba20039c-19a3-96da-c938-89af67bca791@dunelm.org.uk","subject":"Re: [PATCH v2 0/5] Documentation: updates and a correction around 'ORIG_HEAD'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-01-13T17:56:52Z","receivedAt":"2023-01-13T18:03:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Phillip Wood writes:\n\n> Hi Philippe\n>\n> On 10/01/2023 13:15, Philippe Blain via GitGitGadget wrote:\n>> * added a link to the mailing list thread in the commit message of 5/5.\n>> v1: Documentation: updates and a correction around 'ORIG_HEAD'\n>> This series' initial motivation was to clear up a confusion that\n>> arose in\n>> [1] where it was noticed that 'ORIG_HEAD' is not guaranteed to point to the\n>> original branch tip at the end of the rebase if 'git reset' is used during\n>> the rebase.\n>> Patch 5/5 adds a note to 'git rebase's documentation to make that\n>> explicit.\n>> When taking a look at the existing documentation mentioning 'ORIG_HEAD', I\n>> also found an error in an example (patch 1/5), other small inconsistencies\n>> (patch 2-3/5), and a potential improvement (patch 4/5).\n>\n> Thanks for doing this, I think the adding a note to the rebase\n> documentation is a good idea given the confusion that's been\n> reported. The patches all look great to me apart from patch 4 where I\n> share Junio's concerns about the readability and maintenance burden of\n> the list of commands. I was surprised to learn that merge also sets\n> ORIG_HEAD, thanks for being so thorough.\n\nThanks for reviewing, and thanks for writing, the patch. Let's\nqueue and merge it to 'next'.\n\n"}]}