Re: [FIXED PATCH] Make rebase save ORIG_HEAD if changing current branch
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:44:54
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
Possibly related (same subject, not in this thread)
- 2016-06-15 · Re: [FIXED PATCH] Make rebase save ORIG_HEAD if changing current branch · Junio C Hamano <hidden>
- 2016-06-15 · Re: [FIXED PATCH] Make rebase save ORIG_HEAD if changing current branch · Brian Gernhardt <hidden>
- 2016-06-15 · Re: [FIXED PATCH] Make rebase save ORIG_HEAD if changing current branch · Junio C Hamano <hidden>
- 2016-06-15 · Re: [FIXED PATCH] Make rebase save ORIG_HEAD if changing current branch · Mike Hommey <hidden>
- 2016-06-15 · Re: [FIXED PATCH] Make rebase save ORIG_HEAD if changing current branch · Junio C Hamano <hidden>
Junio C Hamano [off-list ref] writes:
The idea behind ORIG_HEAD is to have an anchoring point before an operation that moves your HEAD in a drastic way. Think if it as a poor-man's reflog -- in fact it predates reflog. That is why reset saves away the HEAD before it does its thing, so that you can easily say "Oops, I did not mean it -- reset ORIG_HEAD" to flip back to the previous state. Both a fast-forward merge and a real merge can be undone by resetting back to ORIG_HEAD.
I've also seen people complain (quite rightfully) that these FOO_HEAD pseudo refs are not documented in a central place. How about doing this? It should make it clear what ORIG_HEAD is meant to record, while describing others. And to answer your "git rebase --onto this from that-branch" question, I think ORIG_HEAD should record the tip of that-branch before rebase takes place, not the commit you happened to be at before running it. Switching branch to that-branch is not the drastic and unforseeable part. The drastic and unforseeable change is rebasing and seeing that the rebased result does not work with the new upstream `from`, and the user would want to have a way to quickly rewind the tip of the branch back to the state before the rebase. The new paragraph added by this patch should hopefully make this reasoning more clear. -- >8 -- Documentation: update sections on naming revisions and revision ranges Various *_HEAD pseudo refs were not documented in any central place. Especially since we may be teaching rebase and am to record ORIG_HEAD, it would be a good time to do so. While at it, reword the explanation on r1..r2 notation to reduce confusion. Signed-off-by: Junio C Hamano <redacted> --- Documentation/git-rev-parse.txt | 20 +++++++++++++++----- 1 files changed, 15 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 378a312..7184274 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt@@ -166,7 +166,7 @@ blobs contained in a commit. first match in the following rules: . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually - useful only for `HEAD`, `FETCH_HEAD` and `MERGE_HEAD`); + useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD` and `MERGE_HEAD`); . otherwise, `$GIT_DIR/refs/<name>` if exists;
@@ -177,6 +177,16 @@ blobs contained in a commit. . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists; . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists. ++ +HEAD names the commit your changes in the working tree is based on. +FETCH_HEAD records the branch you fetched from a remote repository +with your last 'git-fetch' invocation. +ORIG_HEAD is created by commands that moves your HEAD in a drastic +way, to record the position of the HEAD before their operation, so that +you can change the tip of the branch back to the state before you ran +them easily. +MERGE_HEAD records the commit(s) you are merging into your branch +when you run 'git-merge'. * A ref followed by the suffix '@' with a date specification enclosed in a brace
@@ -289,10 +299,10 @@ notation is used. E.g. "`{caret}r1 r2`" means commits reachable from `r2` but exclude the ones reachable from `r1`. This set operation appears so often that there is a shorthand -for it. "`r1..r2`" is equivalent to "`{caret}r1 r2`". It is -the difference of two sets (subtract the set of commits -reachable from `r1` from the set of commits reachable from -`r2`). +for it. When you have two commits `r1` and `r2` (named according +to the syntax explained in SPECIFYING REVISIONS above), you can ask +for commits that are reachable from r2 but not from r1 by +"`{caret}r1 r2`" and it can be written as "`r1..r2`". A similar notation "`r1\...r2`" is called symmetric difference of `r1` and `r2` and is defined as