From e29678bb7c967f731965829e38aab8dd88e5c031 Mon Sep 17 00:00:00 2001 From: Philippe Blain Date: Tue, 10 Jan 2023 13:15:17 +0000 Subject: [PATCH 1/5] git-cherry-pick.txt: do not use 'ORIG_HEAD' in example 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 Acked-by: Phillip Wood Signed-off-by: Junio C Hamano --- 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 1e8ac9df60..fdcad3d200 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^`. From d03c773cf6c9d425a8d25af7a45775e280fd6d81 Mon Sep 17 00:00:00 2001 From: Philippe Blain Date: Tue, 10 Jan 2023 13:15:18 +0000 Subject: [PATCH 2/5] git-reset.txt: mention 'ORIG_HEAD' in the Description 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 Acked-by: Phillip Wood Signed-off-by: Junio C Hamano --- 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 01cb4c9b9c..79ad5643ee 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: + -- From 0c514d576685f72a42cf60a2690984fbc7f54a31 Mon Sep 17 00:00:00 2001 From: Philippe Blain Date: Tue, 10 Jan 2023 13:15:19 +0000 Subject: [PATCH 3/5] git-merge.txt: mention 'ORIG_HEAD' in the Description 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 Acked-by: Phillip Wood Signed-off-by: Junio C Hamano --- 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 2d6a1391c8..0aeff572a5 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 From c6eec9cb3677fe91c887181c0a184cb30627fca2 Mon Sep 17 00:00:00 2001 From: Philippe Blain Date: Tue, 10 Jan 2023 13:15:20 +0000 Subject: [PATCH 4/5] revisions.txt: be explicit about commands writing 'ORIG_HEAD' 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 Acked-by: Phillip Wood Signed-off-by: Junio C Hamano --- Documentation/revisions.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 0d2e55d781..9aa58052bc 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 From f1c9243fc5e5234ed00d3ecb71f2629c18d791ab Mon Sep 17 00:00:00 2001 From: Philippe Blain Date: Tue, 10 Jan 2023 13:15:21 +0000 Subject: [PATCH 5/5] git-rebase.txt: add a note about 'ORIG_HEAD' being overwritten '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 Acked-by: Phillip Wood Signed-off-by: Junio C Hamano --- Documentation/git-rebase.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index f9675bd24e..d811c1cf44 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