[PATCH 0/5] Documentation: updates and a correction around 'ORIG_HEAD'

[PATCH 0/5] Documentation: updates and a correction around 'ORIG_HEAD'

[Philippe Blain via GitGitGadget]

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

[PATCH 1/5] git-cherry-pick.txt: do not use 'ORIG_HEAD' in example

[Philippe Blain via GitGitGadget]

From: Philippe Blain <levraiphilippeblain@gmail.com>

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 <levraiphilippeblain@gmail.com>
---
 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

[PATCH 2/5] git-reset.txt: mention 'ORIG_HEAD' in the Description

[Philippe Blain via GitGitGadget]

From: Philippe Blain <levraiphilippeblain@gmail.com>

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.

Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
 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' [<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:
 +
 --
-- 
gitgitgadget

[PATCH 3/5] git-merge.txt: mention 'ORIG_HEAD' in the Description

[Philippe Blain via GitGitGadget]

From: Philippe Blain <levraiphilippeblain@gmail.com>

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 <levraiphilippeblain@gmail.com>
---
 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

[PATCH 4/5] revisions.txt: be explicit about commands writing 'ORIG_HEAD'

[Philippe Blain via GitGitGadget]

From: Philippe Blain <levraiphilippeblain@gmail.com>

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 <levraiphilippeblain@gmail.com>
---
 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

[PATCH 5/5] git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten

[Philippe Blain via GitGitGadget]

From: Philippe Blain <levraiphilippeblain@gmail.com>

'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 <erik@cervined.in>
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
 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 `<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
-- 
gitgitgadget

Re: [PATCH 1/5] git-cherry-pick.txt: do not use 'ORIG_HEAD' in example

[Junio C Hamano]

"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> 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^`.

Re: [PATCH 4/5] revisions.txt: be explicit about commands writing 'ORIG_HEAD'

[Junio C Hamano]

"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> 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

Re: [PATCH 5/5] git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten

[Junio C Hamano]

"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Philippe Blain <levraiphilippeblain@gmail.com>
>
> '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.

Re: [PATCH 1/5] git-cherry-pick.txt: do not use 'ORIG_HEAD' in example

[Philippe Blain]

Hi Junio,

Le 2023-01-07 à 21:05, Junio C Hamano a écrit :
> "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> 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.

Re: [PATCH 4/5] revisions.txt: be explicit about commands writing 'ORIG_HEAD'

[Philippe Blain]

Hi Junio,

Le 2023-01-07 à 21:08, Junio C Hamano a écrit :
> "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> 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.

Re: [PATCH 5/5] git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten

[Philippe Blain]

Hi Junio,

Le 2023-01-07 à 21:16, Junio C Hamano a écrit :
> "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
>> From: Philippe Blain <levraiphilippeblain@gmail.com>
>>
>> '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.

[PATCH v2 0/5] Documentation: updates and a correction around 'ORIG_HEAD'

[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/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 <erik@cervined.in>
          Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
      

-- 
gitgitgadget

[PATCH v2 1/5] git-cherry-pick.txt: do not use 'ORIG_HEAD' in example

[Philippe Blain via GitGitGadget]

From: Philippe Blain <levraiphilippeblain@gmail.com>

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 <levraiphilippeblain@gmail.com>
---
 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

[PATCH v2 2/5] git-reset.txt: mention 'ORIG_HEAD' in the Description

[Philippe Blain via GitGitGadget]

From: Philippe Blain <levraiphilippeblain@gmail.com>

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.

Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
 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' [<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:
 +
 --
-- 
gitgitgadget

[PATCH v2 3/5] git-merge.txt: mention 'ORIG_HEAD' in the Description

[Philippe Blain via GitGitGadget]

From: Philippe Blain <levraiphilippeblain@gmail.com>

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 <levraiphilippeblain@gmail.com>
---
 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

[PATCH v2 4/5] revisions.txt: be explicit about commands writing 'ORIG_HEAD'

[Philippe Blain via GitGitGadget]

From: Philippe Blain <levraiphilippeblain@gmail.com>

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 <levraiphilippeblain@gmail.com>
---
 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

[PATCH v2 5/5] git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten

[Philippe Blain via GitGitGadget]

From: Philippe Blain <levraiphilippeblain@gmail.com>

'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 <erik@cervined.in>
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
 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 `<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
-- 
gitgitgadget

Re: [PATCH v2 0/5] Documentation: updates and a correction around 'ORIG_HEAD'

[Phillip Wood]

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 <erik@cervined.in>
>            Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
>        
> 

Re: [PATCH v2 0/5] Documentation: updates and a correction around 'ORIG_HEAD'

[Junio C Hamano]

Phillip Wood <phillip.wood123@gmail.com> 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'.