From: Junio C Hamano <gitster@pobox•com>
To: Git List <git@vger•kernel.org>
Cc: Brian Gernhardt <benji@silverinsanity•com>
Subject: Re: [FIXED PATCH] Make rebase save ORIG_HEAD if changing current branch
Date: Mon, 07 Jul 2008 14:58:58 -0700 [thread overview]
Message-ID: <7vod591hlp.fsf@gitster.siamese.dyndns.org> (raw)
In-Reply-To: <7vbq1a8ay3.fsf@gitster.siamese.dyndns.org> (Junio C. Hamano's message of "Sun, 06 Jul 2008 23:28:36 -0700")
Junio C Hamano <gitster@pobox•com> 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 <gitster@pobox•com>
---
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
next prev parent reply other threads:[~2008-07-07 22:00 UTC|newest]
Thread overview: 28+ messages / expand[flat|nested] mbox.gz Atom feed top
2008-07-06 21:22 [FIXED PATCH] Make rebase save ORIG_HEAD if changing current branch Brian Gernhardt
2008-07-07 4:43 ` Junio C Hamano
2008-07-07 5:16 ` Brian Gernhardt
2008-07-07 5:24 ` Junio C Hamano
2008-07-07 6:28 ` Junio C Hamano
2008-07-07 6:48 ` Junio C Hamano
2008-07-07 11:18 ` Theodore Tso
2008-07-07 11:42 ` Jakub Narebski
2008-07-07 15:03 ` Brian Gernhardt
2008-07-08 4:26 ` Jeff King
2008-07-08 14:32 ` Brian Gernhardt
2008-07-07 14:36 ` Brian Gernhardt
2008-07-07 18:04 ` Junio C Hamano
2008-07-07 21:58 ` Junio C Hamano [this message]
2008-07-07 22:14 ` Jakub Narebski
2008-07-07 22:33 ` Junio C Hamano
2008-07-07 22:58 ` Jakub Narebski
2008-07-08 3:24 ` Brian Gernhardt
2008-07-08 4:12 ` [PATCH] Documentation: mention ORIG_HEAD in am, merge, and rebase Brian Gernhardt
2008-07-08 19:23 ` Junio C Hamano
2008-07-08 19:28 ` Brian Gernhardt
2008-07-08 3:28 ` [FIXED PATCH] Make rebase save ORIG_HEAD if changing current branch Jay Soffian
2008-07-07 5:41 ` Mike Hommey
2008-07-07 5:46 ` Junio C Hamano
2008-07-07 5:48 ` Mike Hommey
2008-07-07 6:14 ` Nanako Shiraishi
2008-07-07 7:16 ` Re* " Junio C Hamano
2008-07-07 14:36 ` Brian Gernhardt
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=7vod591hlp.fsf@gitster.siamese.dyndns.org \
--to=gitster@pobox$(echo .)com \
--cc=benji@silverinsanity$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox