# [PATCH 0/5] Documentation: updates and a correction around 'ORIG_HEAD' 20 messages from 2023-01-07 to 2023-01-13. Participants: Philippe Blain via GitGitGadget, Junio C Hamano, Philippe Blain, Phillip Wood. Thread: https://gitlist.dev/t/59046 ## Philippe Blain via GitGitGadget, 2023-01-07 19:39 Subject: [PATCH 0/5] Documentation: updates and a correction around 'ORIG_HEAD' Message-ID: URL: https://gitlist.dev/e/pull.1456.git.1673120359.gitgitgadget%40gmail.com ``` This series' initial motivation was to clear up a confusion that arose in [1] where it was noticed that 'ORIG_HEAD' is not guaranteed to point to the original branch tip at the end of the rebase if 'git reset' is used during the rebase. Patch 5/5 adds a note to 'git rebase's documentation to make that explicit. When taking a look at the existing documentation mentioning 'ORIG_HEAD', I also found an error in an example (patch 1/5), other small inconsistencies (patch 2-3/5), and a potential improvement (patch 4/5). Cheers, Philippe. [1] https://lore.kernel.org/git/1b2b8e98-5506-a1e6-6059-a967757b3bb8@gmail.com/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0 Philippe Blain (5): git-cherry-pick.txt: do not use 'ORIG_HEAD' in example git-reset.txt: mention 'ORIG_HEAD' in the Description git-merge.txt: mention 'ORIG_HEAD' in the Description revisions.txt: be explicit about commands writing 'ORIG_HEAD' git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten Documentation/git-cherry-pick.txt | 2 +- Documentation/git-merge.txt | 3 ++- Documentation/git-rebase.txt | 7 +++++++ Documentation/git-reset.txt | 3 ++- Documentation/revisions.txt | 3 ++- 5 files changed, 14 insertions(+), 4 deletions(-) base-commit: 4dbebc36b0893f5094668ddea077d0e235560b16 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1456%2Fphil-blain%2Fdoc-orig-head-v1 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1456/phil-blain/doc-orig-head-v1 Pull-Request: https://github.com/gitgitgadget/git/pull/1456 -- gitgitgadget ``` ## Philippe Blain via GitGitGadget, 2023-01-07 19:39 Subject: [PATCH 1/5] git-cherry-pick.txt: do not use 'ORIG_HEAD' in example Message-ID: <74b2d5a9144e4893311d9acfb0b5e8268da6f0f0.1673120359.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/74b2d5a9144e4893311d9acfb0b5e8268da6f0f0.1673120359.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Philippe Blain Commit 67ac1e1d57 (cherry-pick/revert: add support for -X/--strategy-option, 2010-12-10) added an example to the documentation of 'git cherry-pick'. This example mentions how to abort a failed cherry-pick and retry with an additional merge strategy option. The command used in the example to abort the cherry-pick is 'git reset --merge ORIG_HEAD', but cherry-pick does not write 'ORIG_HEAD' before starting its operation. So this command would checkout a commit unrelated to what was at HEAD when the user invoked cherry-pick. Use 'git cherry-pick --abort' instead. Signed-off-by: Philippe Blain --- Documentation/git-cherry-pick.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 1e8ac9df602..fdcad3d2006 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -219,7 +219,7 @@ again, this time exercising more care about matching up context lines. ------------ $ git cherry-pick topic^ <1> $ git diff <2> -$ git reset --merge ORIG_HEAD <3> +$ git cherry-pick --abort <3> $ git cherry-pick -Xpatience topic^ <4> ------------ <1> apply the change that would be shown by `git show topic^`. -- gitgitgadget ``` ## Philippe Blain via GitGitGadget, 2023-01-07 19:39 Subject: [PATCH 2/5] git-reset.txt: mention 'ORIG_HEAD' in the Description Message-ID: URL: https://gitlist.dev/e/f25c71fd4c31b5c08974b275b3ab23b6c8048fce.1673120359.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Philippe Blain The fact that 'git reset' writes 'ORIG_HEAD' before changing HEAD is mentioned in an example, but is missing from the 'Description' section. Mention it in the discussion of the "'git reset' [] []" form of the command. Signed-off-by: Philippe Blain --- Documentation/git-reset.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 01cb4c9b9c5..79ad5643eed 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -49,7 +49,8 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. 'git reset' [] []:: This form resets the current branch head to `` and possibly updates the index (resetting it to the tree of ``) and - the working tree depending on ``. If `` is omitted, + the working tree depending on ``. Before the operation, `ORIG_HEAD` + is set to the tip of the current branch. If `` is omitted, defaults to `--mixed`. The `` must be one of the following: + -- -- gitgitgadget ``` ## Philippe Blain via GitGitGadget, 2023-01-07 19:39 Subject: [PATCH 3/5] git-merge.txt: mention 'ORIG_HEAD' in the Description Message-ID: URL: https://gitlist.dev/e/e488ad3ce1d2e227f5440fc04d0f6aeb6347a82a.1673120359.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Philippe Blain The fact that 'git merge' writes 'ORIG_HEAD' before performing the merge is missing from the documentation of the command. Mention it in the 'Description' section. Signed-off-by: Philippe Blain --- Documentation/git-merge.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 2d6a1391c89..0aeff572a59 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -37,7 +37,8 @@ Then "`git merge topic`" will replay the changes made on the `topic` branch since it diverged from `master` (i.e., `E`) until its current commit (`C`) on top of `master`, and record the result in a new commit along with the names of the two parent commits and -a log message from the user describing the changes. +a log message from the user describing the changes. Before the operation, +`ORIG_HEAD` is set to the tip of the current branch (`C`). ------------ A---B---C topic -- gitgitgadget ``` ## Philippe Blain via GitGitGadget, 2023-01-07 19:39 Subject: [PATCH 4/5] revisions.txt: be explicit about commands writing 'ORIG_HEAD' Message-ID: <302b789a4869c2aa8a0de2f71a2725c6c567685f.1673120359.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/302b789a4869c2aa8a0de2f71a2725c6c567685f.1673120359.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Philippe Blain When mentioning 'ORIG_HEAD', be explicit about which command write that pseudo-ref, namely 'git am', 'git merge', 'git rebase' and 'git reset'. Signed-off-by: Philippe Blain --- Documentation/revisions.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 0d2e55d7819..9aa58052bc7 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -49,7 +49,8 @@ characters and to avoid word splitting. `FETCH_HEAD` records the branch which you fetched from a remote repository with your last `git fetch` invocation. `ORIG_HEAD` is created by commands that move your `HEAD` in a drastic -way, to record the position of the `HEAD` before their operation, so that +way (`git am`, `git merge`, `git rebase`, `git reset`), +to record the position of the `HEAD` before their operation, so that you can easily change the tip of the branch back to the state before you ran them. `MERGE_HEAD` records the commit(s) which you are merging into your branch -- gitgitgadget ``` ## Philippe Blain via GitGitGadget, 2023-01-07 19:39 Subject: [PATCH 5/5] git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten Message-ID: <9ef427a9a2adfb6a47d13103f00a64df96725560.1673120359.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/9ef427a9a2adfb6a47d13103f00a64df96725560.1673120359.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Philippe Blain 'ORIG_HEAD' is written at the start of the rebase, but is not guaranteed to still point to the original branch tip at the end of the rebase. Indeed, using other commands that write 'ORIG_HEAD' during the rebase, like splitting a commit using 'git reset HEAD^', will lead to 'ORIG_HEAD' being overwritten. Add a note about that in the 'Description' section, and mention the more robust alternative of using the branch's reflog. Reported-by: Erik Cervin Edin Signed-off-by: Philippe Blain --- Documentation/git-rebase.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index f9675bd24e6..d811c1cf443 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -38,6 +38,13 @@ The current branch is reset to `` or `` if the `git reset --hard ` (or ``). `ORIG_HEAD` is set to point at the tip of the branch before the reset. +[NOTE] +`ORIG_HEAD` is not guaranteed to still point to the previous branch tip +at the end of the rebase if other commands that write that pseudo-ref +(e.g. `git reset`) are used during the rebase. The previous branch tip, +however, is accessible using the reflog of the current branch +(i.e. `@{1}`, see linkgit:gitrevisions[7]). + The commits that were previously saved into the temporary area are then reapplied to the current branch, one by one, in order. Note that any commits in `HEAD` which introduce the same textual changes as a commit -- gitgitgadget ``` ## Junio C Hamano, 2023-01-08 02:05 Subject: Re: [PATCH 1/5] git-cherry-pick.txt: do not use 'ORIG_HEAD' in example Message-ID: URL: https://gitlist.dev/e/xmqqh6x1232e.fsf%40gitster.g In-Reply-To: <74b2d5a9144e4893311d9acfb0b5e8268da6f0f0.1673120359.git.gitgitgadget@gmail.com> ``` "Philippe Blain via GitGitGadget" writes: > The command used in the example to abort the cherry-pick is 'git reset > --merge ORIG_HEAD', but cherry-pick does not write 'ORIG_HEAD' before > starting its operation. Sorry, but I am confused. Doesn't <1> update ORIG_HEAD used by <3>? > $ git cherry-pick topic^ <1> > $ git diff <2> > -$ git reset --merge ORIG_HEAD <3> > +$ git cherry-pick --abort <3> > $ git cherry-pick -Xpatience topic^ <4> > ------------ > <1> apply the change that would be shown by `git show topic^`. ``` ## Junio C Hamano, 2023-01-08 02:08 Subject: Re: [PATCH 4/5] revisions.txt: be explicit about commands writing 'ORIG_HEAD' Message-ID: URL: https://gitlist.dev/e/xmqqcz7p22x5.fsf%40gitster.g In-Reply-To: <302b789a4869c2aa8a0de2f71a2725c6c567685f.1673120359.git.gitgitgadget@gmail.com> ``` "Philippe Blain via GitGitGadget" writes: > -way, to record the position of the `HEAD` before their operation, so that > +way (`git am`, `git merge`, `git rebase`, `git reset`), Let's not commit that these four will forever stay to be the commands that uses ORIG_HEAD. Perhaps "(e.g. `git am`, ...)"? > +to record the position of the `HEAD` before their operation, so that ``` ## Junio C Hamano, 2023-01-08 02:16 Subject: Re: [PATCH 5/5] git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten Message-ID: URL: https://gitlist.dev/e/xmqq4jt122k2.fsf%40gitster.g In-Reply-To: <9ef427a9a2adfb6a47d13103f00a64df96725560.1673120359.git.gitgitgadget@gmail.com> ``` "Philippe Blain via GitGitGadget" writes: > From: Philippe Blain > > 'ORIG_HEAD' is written at the start of the rebase, but is not guaranteed > to still point to the original branch tip at the end of the rebase. > > Indeed, using other commands that write 'ORIG_HEAD' during the rebase, > like splitting a commit using 'git reset HEAD^', will lead to 'ORIG_HEAD' > being overwritten. Is that a news? If a user does "reset", the user is asking that HEAD is changed and the old state kept in ORIG_HEAD at the same time, so while it is not wrong per-se to say that user can clobber ORIG_HEAD after rebase sets it first, it is pretty much expected, no? What would be unexpected is if "rebase" overwrote ORIG_HEAD after user did all these other things while it gave control back and then it took control back, and it would be worth documenting. Having said that, I do not mind documenting this. I am not sure "is not guaranteed" is a good way to phrase what happens, though. > +[NOTE] > +`ORIG_HEAD` is not guaranteed to still point to the previous branch tip > +at the end of the rebase if other commands that write that pseudo-ref > +(e.g. `git reset`) are used during the rebase. The previous branch tip, > +however, is accessible using the reflog of the current branch > +(i.e. `@{1}`, see linkgit:gitrevisions[7]). `ORIG_HEAD` is set to point at the tip of the previous branch when `rebase` begins, but the user can run commands (e.g. "git reset") that overwrites `ORIG_HEAD` while `rebase` gives control to the user (e.g. while asking to resolve conflict). It is excellent to mention reflog, which is very much an upward compatible replacement of ORIG_HEAD. Thanks. ``` ## Philippe Blain, 2023-01-09 13:56 Subject: Re: [PATCH 1/5] git-cherry-pick.txt: do not use 'ORIG_HEAD' in example Message-ID: <4525699c-eed5-4da6-b469-b73b87525b23@gmail.com> URL: https://gitlist.dev/e/4525699c-eed5-4da6-b469-b73b87525b23%40gmail.com In-Reply-To: ``` Hi Junio, Le 2023-01-07 à 21:05, Junio C Hamano a écrit : > "Philippe Blain via GitGitGadget" writes: > >> The command used in the example to abort the cherry-pick is 'git reset >> --merge ORIG_HEAD', but cherry-pick does not write 'ORIG_HEAD' before >> starting its operation. > > Sorry, but I am confused. Doesn't <1> update ORIG_HEAD used by <3>? > >> $ git cherry-pick topic^ <1> >> $ git diff <2> >> -$ git reset --merge ORIG_HEAD <3> >> +$ git cherry-pick --abort <3> >> $ git cherry-pick -Xpatience topic^ <4> >> ------------ >> <1> apply the change that would be shown by `git show topic^`. > No, as far as I was able to test and from my reading of the code, cherry-pick does not write ORIG_HEAD. Here is a little script that demonstrates this: ˋˋˋ #!/bin/sh rm -rf test git -c init.defaultBranch=master init test ( cd test echo hello>file git add file git commit -m initial git branch other echo two>>file git commit -am two git checkout other echo three >>file git commit -am three git checkout master # This writes ORIG_HEAD as 'two' git reset HEAD^ git commit -a -m two-redone # This does not git cherry-pick other # This shows ORIG_HEAD written by reset: echo ORIG_HEAD is: git log --oneline -1 ORIG_HEAD # Whereas HEAD is 'two-redone': echo HEAD is: git log --oneline -1 HEAD ) ˋˋˋ Looking at the code, 'git grep -p ORIG_HEAD \*.c' reveals the only builtin that write ORIG_HEAD are am, merge, rebase and reset, and the only library code that involves ORIG_HEAD is reset.c::reset_head. Moreover, 'git grep -p [^a-z_]reset_head \*.c' reveals that the only non-builtin user of reset.c::reset_head is sequencer.c::create_autostash, in which the RESET_ORIG_HEAD flag of 'struct reset_head_opts ropts' is not set. That is what convinced me that cherry-pick does not write ORIG_HEAD. Thanks, Philippe. ``` ## Philippe Blain, 2023-01-09 14:00 Subject: Re: [PATCH 4/5] revisions.txt: be explicit about commands writing 'ORIG_HEAD' Message-ID: <530a9dc9-dc16-fe26-954c-27daabf9e9bd@gmail.com> URL: https://gitlist.dev/e/530a9dc9-dc16-fe26-954c-27daabf9e9bd%40gmail.com In-Reply-To: ``` Hi Junio, Le 2023-01-07 à 21:08, Junio C Hamano a écrit : > "Philippe Blain via GitGitGadget" writes: > >> -way, to record the position of the `HEAD` before their operation, so that >> +way (`git am`, `git merge`, `git rebase`, `git reset`), > > Let's not commit that these four will forever stay to be the > commands that uses ORIG_HEAD. Perhaps "(e.g. `git am`, ...)"? > >> +to record the position of the `HEAD` before their operation, so that > I think I prefer being explicit in the documentation. It's easier for a user wanting to learn which commands write that pseudo-ref to have them all listed at the same place. If other commands learn to write it, we can update the list here. That said, I can live with that patch being tweaked in the next iteration if people feel strongly about an explicit list. Philippe. ``` ## Philippe Blain, 2023-01-09 18:22 Subject: Re: [PATCH 5/5] git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten Message-ID: <85da5311-bef6-88d9-850d-888d874f6988@gmail.com> URL: https://gitlist.dev/e/85da5311-bef6-88d9-850d-888d874f6988%40gmail.com In-Reply-To: ``` Hi Junio, Le 2023-01-07 à 21:16, Junio C Hamano a écrit : > "Philippe Blain via GitGitGadget" writes: > >> From: Philippe Blain >> >> 'ORIG_HEAD' is written at the start of the rebase, but is not guaranteed >> to still point to the original branch tip at the end of the rebase. >> >> Indeed, using other commands that write 'ORIG_HEAD' during the rebase, >> like splitting a commit using 'git reset HEAD^', will lead to 'ORIG_HEAD' >> being overwritten. > > Is that a news? If a user does "reset", the user is asking that > HEAD is changed and the old state kept in ORIG_HEAD at the same > time, so while it is not wrong per-se to say that user can clobber > ORIG_HEAD after rebase sets it first, it is pretty much expected, > no? I forgot to add a link to the mailing list thread and just added a Reported-by trailer here, but it was not expected by at least 2 users (including me) [1]. [1] https://lore.kernel.org/git/28ebf03b-e8bb-3769-556b-c9db17e43dbb@gmail.com/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0 I think of 'git reset HEAD^' during a rebase, to split a existing commit, as rebase-related operation (it could almost be a different instruction in the TODO list), and so my expectation was that ORIG_HEAD at the end of the rebase would not be changed by what I did during the rebase. But I can see how it would be confusing for people that would expect ORIG_HEAD to point to the pre-reset HEAD, and so I just thought I'd point that out in the doc to avoid potential future confusion. > > What would be unexpected is if "rebase" overwrote ORIG_HEAD after > user did all these other things while it gave control back and then > it took control back, and it would be worth documenting. > > Having said that, I do not mind documenting this. I am not sure "is > not guaranteed" is a good way to phrase what happens, though. I use that phrasing because the 'gitrevisions' entry on 'ORIG_HEAD' says: `ORIG_HEAD` is created by commands that move your `HEAD` in a drastic way ([...]), to record the position of the `HEAD` before their operation, so that you can easily change the tip of the branch back to the state before you ran them. so it might be read to mean that 'ORIG_HEAD' always points to the pre-operation state. I'm open to other wording, though. > >> +[NOTE] >> +`ORIG_HEAD` is not guaranteed to still point to the previous branch tip >> +at the end of the rebase if other commands that write that pseudo-ref >> +(e.g. `git reset`) are used during the rebase. The previous branch tip, >> +however, is accessible using the reflog of the current branch >> +(i.e. `@{1}`, see linkgit:gitrevisions[7]). > > `ORIG_HEAD` is set to point at the tip of the previous branch > when `rebase` begins, but the user can run commands (e.g. "git > reset") that overwrites `ORIG_HEAD` while `rebase` gives control > to the user (e.g. while asking to resolve conflict). > > It is excellent to mention reflog, which is very much an upward > compatible replacement of ORIG_HEAD. > > Thanks. > Thanks, I'll consider that wording for v2. Cheers, Philippe. ``` ## Philippe Blain via GitGitGadget, 2023-01-10 13:15 Subject: [PATCH v2 1/5] git-cherry-pick.txt: do not use 'ORIG_HEAD' in example Message-ID: <74b2d5a9144e4893311d9acfb0b5e8268da6f0f0.1673356522.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/74b2d5a9144e4893311d9acfb0b5e8268da6f0f0.1673356522.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Philippe Blain Commit 67ac1e1d57 (cherry-pick/revert: add support for -X/--strategy-option, 2010-12-10) added an example to the documentation of 'git cherry-pick'. This example mentions how to abort a failed cherry-pick and retry with an additional merge strategy option. The command used in the example to abort the cherry-pick is 'git reset --merge ORIG_HEAD', but cherry-pick does not write 'ORIG_HEAD' before starting its operation. So this command would checkout a commit unrelated to what was at HEAD when the user invoked cherry-pick. Use 'git cherry-pick --abort' instead. Signed-off-by: Philippe Blain --- Documentation/git-cherry-pick.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 1e8ac9df602..fdcad3d2006 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -219,7 +219,7 @@ again, this time exercising more care about matching up context lines. ------------ $ git cherry-pick topic^ <1> $ git diff <2> -$ git reset --merge ORIG_HEAD <3> +$ git cherry-pick --abort <3> $ git cherry-pick -Xpatience topic^ <4> ------------ <1> apply the change that would be shown by `git show topic^`. -- gitgitgadget ``` ## Philippe Blain via GitGitGadget, 2023-01-10 13:15 Subject: [PATCH v2 2/5] git-reset.txt: mention 'ORIG_HEAD' in the Description Message-ID: URL: https://gitlist.dev/e/f25c71fd4c31b5c08974b275b3ab23b6c8048fce.1673356522.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Philippe Blain The fact that 'git reset' writes 'ORIG_HEAD' before changing HEAD is mentioned in an example, but is missing from the 'Description' section. Mention it in the discussion of the "'git reset' [] []" form of the command. Signed-off-by: Philippe Blain --- Documentation/git-reset.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 01cb4c9b9c5..79ad5643eed 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -49,7 +49,8 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. 'git reset' [] []:: This form resets the current branch head to `` and possibly updates the index (resetting it to the tree of ``) and - the working tree depending on ``. If `` is omitted, + the working tree depending on ``. Before the operation, `ORIG_HEAD` + is set to the tip of the current branch. If `` is omitted, defaults to `--mixed`. The `` must be one of the following: + -- -- gitgitgadget ``` ## Philippe Blain via GitGitGadget, 2023-01-10 13:15 Subject: [PATCH v2 3/5] git-merge.txt: mention 'ORIG_HEAD' in the Description Message-ID: URL: https://gitlist.dev/e/e488ad3ce1d2e227f5440fc04d0f6aeb6347a82a.1673356522.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Philippe Blain The fact that 'git merge' writes 'ORIG_HEAD' before performing the merge is missing from the documentation of the command. Mention it in the 'Description' section. Signed-off-by: Philippe Blain --- Documentation/git-merge.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 2d6a1391c89..0aeff572a59 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -37,7 +37,8 @@ Then "`git merge topic`" will replay the changes made on the `topic` branch since it diverged from `master` (i.e., `E`) until its current commit (`C`) on top of `master`, and record the result in a new commit along with the names of the two parent commits and -a log message from the user describing the changes. +a log message from the user describing the changes. Before the operation, +`ORIG_HEAD` is set to the tip of the current branch (`C`). ------------ A---B---C topic -- gitgitgadget ``` ## Philippe Blain via GitGitGadget, 2023-01-10 13:15 Subject: [PATCH v2 0/5] Documentation: updates and a correction around 'ORIG_HEAD' Message-ID: URL: https://gitlist.dev/e/pull.1456.v2.git.1673356521.gitgitgadget%40gmail.com In-Reply-To: ``` * added a link to the mailing list thread in the commit message of 5/5. v1: Documentation: updates and a correction around 'ORIG_HEAD' This series' initial motivation was to clear up a confusion that arose in [1] where it was noticed that 'ORIG_HEAD' is not guaranteed to point to the original branch tip at the end of the rebase if 'git reset' is used during the rebase. Patch 5/5 adds a note to 'git rebase's documentation to make that explicit. When taking a look at the existing documentation mentioning 'ORIG_HEAD', I also found an error in an example (patch 1/5), other small inconsistencies (patch 2-3/5), and a potential improvement (patch 4/5). Cheers, Philippe. [1] https://lore.kernel.org/git/1b2b8e98-5506-a1e6-6059-a967757b3bb8@gmail.com/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0 Philippe Blain (5): git-cherry-pick.txt: do not use 'ORIG_HEAD' in example git-reset.txt: mention 'ORIG_HEAD' in the Description git-merge.txt: mention 'ORIG_HEAD' in the Description revisions.txt: be explicit about commands writing 'ORIG_HEAD' git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten Documentation/git-cherry-pick.txt | 2 +- Documentation/git-merge.txt | 3 ++- Documentation/git-rebase.txt | 7 +++++++ Documentation/git-reset.txt | 3 ++- Documentation/revisions.txt | 3 ++- 5 files changed, 14 insertions(+), 4 deletions(-) base-commit: 4dbebc36b0893f5094668ddea077d0e235560b16 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1456%2Fphil-blain%2Fdoc-orig-head-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1456/phil-blain/doc-orig-head-v2 Pull-Request: https://github.com/gitgitgadget/git/pull/1456 Range-diff vs v1: 1: 74b2d5a9144 = 1: 74b2d5a9144 git-cherry-pick.txt: do not use 'ORIG_HEAD' in example 2: f25c71fd4c3 = 2: f25c71fd4c3 git-reset.txt: mention 'ORIG_HEAD' in the Description 3: e488ad3ce1d = 3: e488ad3ce1d git-merge.txt: mention 'ORIG_HEAD' in the Description 4: 302b789a486 = 4: 302b789a486 revisions.txt: be explicit about commands writing 'ORIG_HEAD' 5: 9ef427a9a2a ! 5: 7eed8f35376 git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten @@ Commit message Indeed, using other commands that write 'ORIG_HEAD' during the rebase, like splitting a commit using 'git reset HEAD^', will lead to 'ORIG_HEAD' - being overwritten. + being overwritten. This causes confusion for some users [1]. Add a note about that in the 'Description' section, and mention the more robust alternative of using the branch's reflog. + [1] https://lore.kernel.org/git/28ebf03b-e8bb-3769-556b-c9db17e43dbb@gmail.com/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0 + Reported-by: Erik Cervin Edin Signed-off-by: Philippe Blain -- gitgitgadget ``` ## Philippe Blain via GitGitGadget, 2023-01-10 13:15 Subject: [PATCH v2 4/5] revisions.txt: be explicit about commands writing 'ORIG_HEAD' Message-ID: <302b789a4869c2aa8a0de2f71a2725c6c567685f.1673356522.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/302b789a4869c2aa8a0de2f71a2725c6c567685f.1673356522.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Philippe Blain When mentioning 'ORIG_HEAD', be explicit about which command write that pseudo-ref, namely 'git am', 'git merge', 'git rebase' and 'git reset'. Signed-off-by: Philippe Blain --- Documentation/revisions.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 0d2e55d7819..9aa58052bc7 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -49,7 +49,8 @@ characters and to avoid word splitting. `FETCH_HEAD` records the branch which you fetched from a remote repository with your last `git fetch` invocation. `ORIG_HEAD` is created by commands that move your `HEAD` in a drastic -way, to record the position of the `HEAD` before their operation, so that +way (`git am`, `git merge`, `git rebase`, `git reset`), +to record the position of the `HEAD` before their operation, so that you can easily change the tip of the branch back to the state before you ran them. `MERGE_HEAD` records the commit(s) which you are merging into your branch -- gitgitgadget ``` ## Philippe Blain via GitGitGadget, 2023-01-10 13:15 Subject: [PATCH v2 5/5] git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten Message-ID: <7eed8f353764774cc7335c51338db6cba14675aa.1673356522.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/7eed8f353764774cc7335c51338db6cba14675aa.1673356522.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Philippe Blain 'ORIG_HEAD' is written at the start of the rebase, but is not guaranteed to still point to the original branch tip at the end of the rebase. Indeed, using other commands that write 'ORIG_HEAD' during the rebase, like splitting a commit using 'git reset HEAD^', will lead to 'ORIG_HEAD' being overwritten. This causes confusion for some users [1]. Add a note about that in the 'Description' section, and mention the more robust alternative of using the branch's reflog. [1] https://lore.kernel.org/git/28ebf03b-e8bb-3769-556b-c9db17e43dbb@gmail.com/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0 Reported-by: Erik Cervin Edin Signed-off-by: Philippe Blain --- Documentation/git-rebase.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index f9675bd24e6..d811c1cf443 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -38,6 +38,13 @@ The current branch is reset to `` or `` if the `git reset --hard ` (or ``). `ORIG_HEAD` is set to point at the tip of the branch before the reset. +[NOTE] +`ORIG_HEAD` is not guaranteed to still point to the previous branch tip +at the end of the rebase if other commands that write that pseudo-ref +(e.g. `git reset`) are used during the rebase. The previous branch tip, +however, is accessible using the reflog of the current branch +(i.e. `@{1}`, see linkgit:gitrevisions[7]). + The commits that were previously saved into the temporary area are then reapplied to the current branch, one by one, in order. Note that any commits in `HEAD` which introduce the same textual changes as a commit -- gitgitgadget ``` ## Phillip Wood, 2023-01-10 20:06 Subject: Re: [PATCH v2 0/5] Documentation: updates and a correction around 'ORIG_HEAD' Message-ID: URL: https://gitlist.dev/e/ba20039c-19a3-96da-c938-89af67bca791%40dunelm.org.uk In-Reply-To: ``` Hi Philippe On 10/01/2023 13:15, Philippe Blain via GitGitGadget wrote: > * added a link to the mailing list thread in the commit message of 5/5. > > v1: Documentation: updates and a correction around 'ORIG_HEAD' > > This series' initial motivation was to clear up a confusion that arose in > [1] where it was noticed that 'ORIG_HEAD' is not guaranteed to point to the > original branch tip at the end of the rebase if 'git reset' is used during > the rebase. > > Patch 5/5 adds a note to 'git rebase's documentation to make that explicit. > When taking a look at the existing documentation mentioning 'ORIG_HEAD', I > also found an error in an example (patch 1/5), other small inconsistencies > (patch 2-3/5), and a potential improvement (patch 4/5). Thanks for doing this, I think the adding a note to the rebase documentation is a good idea given the confusion that's been reported. The patches all look great to me apart from patch 4 where I share Junio's concerns about the readability and maintenance burden of the list of commands. I was surprised to learn that merge also sets ORIG_HEAD, thanks for being so thorough. Best Wishes Phillip > Cheers, > > Philippe. > > [1] > https://lore.kernel.org/git/1b2b8e98-5506-a1e6-6059-a967757b3bb8@gmail.com/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0 > > Philippe Blain (5): > git-cherry-pick.txt: do not use 'ORIG_HEAD' in example > git-reset.txt: mention 'ORIG_HEAD' in the Description > git-merge.txt: mention 'ORIG_HEAD' in the Description > revisions.txt: be explicit about commands writing 'ORIG_HEAD' > git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten > > Documentation/git-cherry-pick.txt | 2 +- > Documentation/git-merge.txt | 3 ++- > Documentation/git-rebase.txt | 7 +++++++ > Documentation/git-reset.txt | 3 ++- > Documentation/revisions.txt | 3 ++- > 5 files changed, 14 insertions(+), 4 deletions(-) > > > base-commit: 4dbebc36b0893f5094668ddea077d0e235560b16 > Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1456%2Fphil-blain%2Fdoc-orig-head-v2 > Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1456/phil-blain/doc-orig-head-v2 > Pull-Request: https://github.com/gitgitgadget/git/pull/1456 > > Range-diff vs v1: > > 1: 74b2d5a9144 = 1: 74b2d5a9144 git-cherry-pick.txt: do not use 'ORIG_HEAD' in example > 2: f25c71fd4c3 = 2: f25c71fd4c3 git-reset.txt: mention 'ORIG_HEAD' in the Description > 3: e488ad3ce1d = 3: e488ad3ce1d git-merge.txt: mention 'ORIG_HEAD' in the Description > 4: 302b789a486 = 4: 302b789a486 revisions.txt: be explicit about commands writing 'ORIG_HEAD' > 5: 9ef427a9a2a ! 5: 7eed8f35376 git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten > @@ Commit message > > Indeed, using other commands that write 'ORIG_HEAD' during the rebase, > like splitting a commit using 'git reset HEAD^', will lead to 'ORIG_HEAD' > - being overwritten. > + being overwritten. This causes confusion for some users [1]. > > Add a note about that in the 'Description' section, and mention the more > robust alternative of using the branch's reflog. > > + [1] https://lore.kernel.org/git/28ebf03b-e8bb-3769-556b-c9db17e43dbb@gmail.com/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0 > + > Reported-by: Erik Cervin Edin > Signed-off-by: Philippe Blain > > ``` ## Junio C Hamano, 2023-01-13 17:56 Subject: Re: [PATCH v2 0/5] Documentation: updates and a correction around 'ORIG_HEAD' Message-ID: URL: https://gitlist.dev/e/xmqqk01q48t7.fsf%40gitster.g In-Reply-To: ``` Phillip Wood writes: > Hi Philippe > > On 10/01/2023 13:15, Philippe Blain via GitGitGadget wrote: >> * added a link to the mailing list thread in the commit message of 5/5. >> v1: Documentation: updates and a correction around 'ORIG_HEAD' >> This series' initial motivation was to clear up a confusion that >> arose in >> [1] where it was noticed that 'ORIG_HEAD' is not guaranteed to point to the >> original branch tip at the end of the rebase if 'git reset' is used during >> the rebase. >> Patch 5/5 adds a note to 'git rebase's documentation to make that >> explicit. >> When taking a look at the existing documentation mentioning 'ORIG_HEAD', I >> also found an error in an example (patch 1/5), other small inconsistencies >> (patch 2-3/5), and a potential improvement (patch 4/5). > > Thanks for doing this, I think the adding a note to the rebase > documentation is a good idea given the confusion that's been > reported. The patches all look great to me apart from patch 4 where I > share Junio's concerns about the readability and maintenance burden of > the list of commands. I was surprised to learn that merge also sets > ORIG_HEAD, thanks for being so thorough. Thanks for reviewing, and thanks for writing, the patch. Let's queue and merge it to 'next'. ```