Re: [FIXED PATCH] Make rebase save ORIG_HEAD if changing current branch

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

Junio C Hamano [off-list ref] writes:

-- >8 --
Documentation: update sections on naming revisions and revision ranges

[...]

While at it, reword the explanation on r1..r2 notation to reduce
confusion.

I'm not sure if the last part is improvement, and it wouldn't be better
to say rather than r1..r2 / ^r1 r2 are "commits that are reachable from
r2, excluding those commits which are reachable from r1" (which translates
into set difference / subtracting set of commits.

-- 
Jakub Narebski
Poland
ShadeHawk on #git

On Jul 7, 2008, at 5:58 PM, Junio C Hamano wrote:

Junio C Hamano [off-list ref] writes:

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.

I just wanted to make sure there was a clear reasoning and to see if  
someone could word it clearly, as I was getting a little cross-eyed.

-- >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.

My only objection is to the "may".  ;-)

Also, perhaps we should either list the commands that set ORIG_HEAD,  
or add a note to that effect in their manpages.  I'll see what wording  
I can come up with, unless you (or someone else) gets to it first of  
course.

While at it, reword the explanation on r1..r2 notation to reduce
confusion.

Looks good.

~~ Brian

On Mon, Jul 7, 2008 at 5:58 PM, Junio C Hamano [off-list ref] wrote:

+HEAD names the commit your changes in the working tree is based on.

How about:

"HEAD names the commit your working tree is based on. This is the tip
of the checked out branch, unless HEAD is detached. (HEAD is said to
be detached if a commit is checked out which is not the tip of any
branch.)"

+FETCH_HEAD records the branch you fetched from a remote repository
+with your last 'git-fetch' invocation.

consistency w/above: s/records/names/

+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.

s/moves/move/; s/can change/can easily change/; s/them easily./them./;

But maybe this reads better:

ORIG_HEAD is created by commands that move HEAD in a drastic way to
record the position of HEAD before their operation, so that the branch
can easily be reset back to its prior state.

+MERGE_HEAD records the commit(s) you are merging into your branch
+when you run 'git-merge'.

So it's the "<remote>" arg or args mentioned in the git-merge man page?

j.

Merge has always set ORIG_HEAD but never mentioned it, while we
recently added it to am and rebase.  These facts should be reflected
in the documentation.

git-reset also sets ORIG_HEAD, but that fact is already mentioned in
the very first example so no changes were needed there.

Signed-off-by: Brian Gernhardt <redacted>
---
 Documentation/git-am.txt     |    6 ++++++
 Documentation/git-merge.txt  |    4 +++-
 Documentation/git-rebase.txt |    3 ++-
 3 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 3863eeb..88ca5f1 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt

@@ -145,6 +145,12 @@ directory exists, so if you decide to start over from scratch,
 run `rm -f -r .dotest` before running the command with mailbox
 names.
 
+Before any patches are applied, ORIG_HEAD is set to the tip of the
+current branch.  This is useful if you have problems with multiple
+commits, like running 'git am' on the wrong branch or an error in the
+commits that is more easily fixed by changing the mailbox (e.g.
+errors in the "From:" lines).
+
 
 SEE ALSO
 --------

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 62f99b5..019e4ca 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt

@@ -81,7 +81,9 @@ Otherwise, merge will refuse to do any harm to your repository
 (that is, it may fetch the objects from remote, and it may even
 update the local branch used to keep track of the remote branch
 with `git pull remote rbranch:lbranch`, but your working tree,
-`.git/HEAD` pointer and index file are left intact).
+`.git/HEAD` pointer and index file are left intact).  In addition,
+merge always sets `.git/ORIG_HEAD` to the original state of HEAD so
+a problematic merge can be removed by using `git reset ORIG_HEAD`.
 
 You may have local modifications in the working tree files.  In
 other words, 'git-diff' is allowed to report changes.

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index f3459c7..37382c4 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt

@@ -26,7 +26,8 @@ of commits that would be shown by `git log <upstream>..HEAD`.
 
 The current branch is reset to <upstream>, or <newbase> if the
 --onto option was supplied.  This has the exact same effect as
-`git reset --hard <upstream>` (or <newbase>).
+`git reset --hard <upstream>` (or <newbase>).  This includes setting
+ORIG_HEAD to the pre-rebase tip of the branch.
 
 The commits that were previously saved into the temporary area are
 then reapplied to the current branch, one by one, in order. Note that

-- 
1.5.6.2.393.g45096

Brian Gernhardt [off-list ref] writes:

I found the above "This includes" part very hard to understand --- it took
me three re-reads to connect "This" and "the exact same effect".  Is it
just me?

I wonder if this is easier to understand:

        The current branch is reset to <upstream>, or <newbase> if the
        --onto option was supplied.  This has the exact same effect as
        `git reset --hard <upstream>` (or <newbase>).  ORIG_HEAD is set
        to point at the tip of the branch before this resetting happens.

On Jul 8, 2008, at 3:23 PM, Junio C Hamano wrote:

Brian Gernhardt [off-list ref] writes:

quoted

diff --git a/Documentation/git-rebase.txt b/Documentation/git- 

rebase.txt
index f3459c7..37382c4 100644

--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt

@@ -26,7 +26,8 @@ of commits that would be shown by `git log  

<upstream>..HEAD`.

The current branch is reset to <upstream>, or <newbase> if the
--onto option was supplied.  This has the exact same effect as
-`git reset --hard <upstream>` (or <newbase>).
+`git reset --hard <upstream>` (or <newbase>).  This includes setting
+ORIG_HEAD to the pre-rebase tip of the branch.

The commits that were previously saved into the temporary area are
then reapplied to the current branch, one by one, in order. Note that

I found the above "This includes" part very hard to understand ---  
it took
me three re-reads to connect "This" and "the exact same effect".  Is  
it
just me?

I thought it perfectly easy to understand.   ;-)  But of course, I  
wrote it.  I also wrote it immediately after reading the git-reset  
manual, which is why I phrased it that way.  On a fresh read, it's  
less obvious.

I wonder if this is easier to understand:

       The current branch is reset to <upstream>, or <newbase> if the
       --onto option was supplied.  This has the exact same effect as
       `git reset --hard <upstream>` (or <newbase>).  ORIG_HEAD is set
       to point at the tip of the branch before this resetting  
happens.

I might say "before the reset" instead of "before this resetting  
happens", as I find the latter slightly awkward.  But that's a minor nit

~~ Brian