Documentation: updates and a correction around 'ORIG_HEAD'
cover 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/[email protected]/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
Signature · 1 line
gitgitgadget
PATCH 1/5 git-cherry-pick.txt: do not use 'ORIG_HEAD' in example
From: Philippe Blain <[email protected]>
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.
--- Documentation/git-cherry-pick.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-cherry-pick.txt +1 -1
@@ -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^`.
Signature · 1 line
gitgitgadget
PATCH 2/5 git-reset.txt: mention 'ORIG_HEAD' in the Description
In reply to Philippe Blain via GitGitGadgetFrom: Philippe Blain <[email protected]>
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' [<mode>] [<commit>]" form of the command.
--- Documentation/git-reset.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/git-reset.txt +2 -1
@@ -49,7 +49,8 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. 'git reset' [<mode>] [<commit>]:: This form resets the current branch head to `<commit>` and possibly updates the index (resetting it to the tree of `<commit>`) and - the working tree depending on `<mode>`. If `<mode>` is omitted, + the working tree depending on `<mode>`. Before the operation, `ORIG_HEAD` + is set to the tip of the current branch. If `<mode>` is omitted, defaults to `--mixed`. The `<mode>` must be one of the following: + --
Signature · 1 line
gitgitgadget
PATCH 3/5 git-merge.txt: mention 'ORIG_HEAD' in the Description
In reply to Philippe Blain via GitGitGadgetFrom: Philippe Blain <[email protected]>
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.
--- Documentation/git-merge.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/git-merge.txt +2 -1
@@ -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
Signature · 1 line
gitgitgadget
PATCH 4/5 revisions.txt: be explicit about commands writing 'ORIG_HEAD'
In reply to Philippe Blain via GitGitGadgetFrom: Philippe Blain <[email protected]>
When mentioning 'ORIG_HEAD', be explicit about which command write that pseudo-ref, namely 'git am', 'git merge', 'git rebase' and 'git reset'.
--- Documentation/revisions.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/revisions.txt +2 -1
@@ -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
Signature · 1 line
gitgitgadget
PATCH 5/5 git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten
In reply to Philippe Blain via GitGitGadgetFrom: Philippe Blain <[email protected]>
'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.
--- Documentation/git-rebase.txt | 7 +++++++ 1 file changed, 7 insertions(+)
Documentation/git-rebase.txt +7 -0
@@ -38,6 +38,13 @@ The current branch is reset to `<upstream>` or `<newbase>` if the `git reset --hard <upstream>` (or `<newbase>`). `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
Signature · 1 line
gitgitgadget
Re: [PATCH 1/5] git-cherry-pick.txt: do not use 'ORIG_HEAD' in example
In reply to Philippe Blain via GitGitGadgetQuoted 3 lines · Philippe Blain via GitGitGadget
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>?
Quoted 7 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^`.
Re: [PATCH 4/5] revisions.txt: be explicit about commands writing 'ORIG_HEAD'
In reply to Philippe Blain via GitGitGadgetDocumentation/revisions.txt characters and to avoid word splitting. · line 52
Quoted 2 lines · Philippe Blain via GitGitGadget
Documentation/revisions.txt +1
-1-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, ...)"?
Quoted 1 line
+to record the position of the
HEADbefore their operation, so that
Re: [PATCH 5/5] git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten
In reply to Philippe Blain via GitGitGadgetQuoted 8 lines · Philippe Blain via GitGitGadget
From: Philippe Blain <[email protected]>
'
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.
Documentation/git-rebase.txt The current branch is reset to `<upstream>` or `<newbase>` if the · line 46
Quoted 6 lines
+[NOTE]
+ORIG_HEADis not guaranteed to still point to the previous branch tipDocumentation/git-rebase.txt +4
-0+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.
Re: [PATCH 1/5] git-cherry-pick.txt: do not use 'ORIG_HEAD' in example
In reply to Junio C HamanoHi Junio,
Le 2023-01-07 à 21:05, Junio C Hamano a écrit :
Quoted 16 lines
Quoted 3 lines · Philippe Blain via GitGitGadget
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_HEADused by <3>?Quoted 7 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^`.
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.
Re: [PATCH 4/5] revisions.txt: be explicit about commands writing 'ORIG_HEAD'
In reply to Junio C HamanoHi Junio,
Le 2023-01-07 à 21:08, Junio C Hamano a écrit :
Quoted 10 lines
Documentation/revisions.txt characters and to avoid word splitting. · line 52
Quoted 2 lines · Philippe Blain via GitGitGadget
Documentation/revisions.txt +1
-1-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, ...)"?Quoted 1 line
+to record the position of the
HEADbefore 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.
Re: [PATCH 5/5] git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten
In reply to Junio C HamanoHi Junio,
Le 2023-01-07 à 21:16, Junio C Hamano a écrit :
Quoted 11 lines
Quoted 8 lines · Philippe Blain via GitGitGadget
From: Philippe Blain <[email protected]>
'
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.
Quoted 5 lines
Is that a news? If a user does "reset", the user is asking that HEAD is changed and the old state kept in
ORIG_HEADat the same time, so while it is not wrong per-se to say that user can clobberORIG_HEADafter 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/[email protected]/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.
Quoted 7 lines
What would be unexpected is if "rebase" overwrote
ORIG_HEADafter 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.
Quoted 13 lines
Documentation/git-rebase.txt The current branch is reset to `<upstream>` or `<newbase>` if the · line 46
Quoted 7 lines
+[NOTE]
+ORIG_HEADis not guaranteed to still point to the previous branch tipDocumentation/git-rebase.txt +4
-0+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_HEADis set to point at the tip of the previous branch whenrebasebegins, but the user can run commands (e.g. "git reset") that overwritesORIG_HEADwhilerebasegives control to the user (e.g. while asking to resolve conflict).
Quoted 5 lines
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.
PATCH v2 1/5 git-cherry-pick.txt: do not use 'ORIG_HEAD' in example
In reply to Philippe Blain via GitGitGadgetFrom: Philippe Blain <[email protected]>
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.
--- Documentation/git-cherry-pick.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-cherry-pick.txt +1 -1
@@ -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^`.
Signature · 1 line
gitgitgadget
v2 cover Documentation: updates and a correction around 'ORIG_HEAD'
In reply to Philippe Blain via GitGitGadget* 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/[email protected]/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/[email protected]/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0
+
Signature · 1 line
gitgitgadget
PATCH v2 2/5 git-reset.txt: mention 'ORIG_HEAD' in the Description
From: Philippe Blain <[email protected]>
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' [<mode>] [<commit>]" form of the command.
--- Documentation/git-reset.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/git-reset.txt +2 -1
@@ -49,7 +49,8 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. 'git reset' [<mode>] [<commit>]:: This form resets the current branch head to `<commit>` and possibly updates the index (resetting it to the tree of `<commit>`) and - the working tree depending on `<mode>`. If `<mode>` is omitted, + the working tree depending on `<mode>`. Before the operation, `ORIG_HEAD` + is set to the tip of the current branch. If `<mode>` is omitted, defaults to `--mixed`. The `<mode>` must be one of the following: + --
Signature · 1 line
gitgitgadget
PATCH v2 3/5 git-merge.txt: mention 'ORIG_HEAD' in the Description
In reply to Philippe Blain via GitGitGadgetFrom: Philippe Blain <[email protected]>
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.
--- Documentation/git-merge.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/git-merge.txt +2 -1
@@ -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
Signature · 1 line
gitgitgadget
PATCH v2 4/5 revisions.txt: be explicit about commands writing 'ORIG_HEAD'
In reply to Philippe Blain via GitGitGadgetFrom: Philippe Blain <[email protected]>
When mentioning 'ORIG_HEAD', be explicit about which command write that pseudo-ref, namely 'git am', 'git merge', 'git rebase' and 'git reset'.
--- Documentation/revisions.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/revisions.txt +2 -1
@@ -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
Signature · 1 line
gitgitgadget
PATCH v2 5/5 git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten
In reply to Philippe Blain via GitGitGadgetFrom: Philippe Blain <[email protected]>
'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/[email protected]/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0
--- Documentation/git-rebase.txt | 7 +++++++ 1 file changed, 7 insertions(+)
Documentation/git-rebase.txt +7 -0
@@ -38,6 +38,13 @@ The current branch is reset to `<upstream>` or `<newbase>` if the `git reset --hard <upstream>` (or `<newbase>`). `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
Signature · 1 line
gitgitgadget
Hi Philippe
Quoted 9 lines · Philippe Blain via GitGitGadget
* 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.
Quoted 4 lines
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
Quoted 50 lines
Cheers,
Philippe.
[1]
https://lore.kernel.org/git/[email protected]/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0Philippe 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 overwrittenDocumentation/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/1456Range-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/[email protected]/T/#m827179c5adcfb504d67f76d03c8e6942b55e5ed0
+Reported-by Erik Cervin Edin <[email protected]>Signed-off-by Philippe Blain <[email protected]>
Quoted 16 lines · Phillip Wood
Hi Philippe
Quoted 4 lines · Philippe Blain via GitGitGadget
* 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 inQuoted 8 lines
[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).
Quoted 6 lines
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'.