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>
Junio C Hamano committed
Jul 7, 2008 at 14:58 UTC
fd11ae0b52b6d059056a32851a916c152befae1a
1 file changed
+15
-5
Documentation/git-rev-parse.txt
+15
-5
@@ -166,7 +166,7 @@ blobs contained in a commit.
166
first match in the following rules:
167
168
. if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
169
- useful only for `HEAD`, `FETCH_HEAD` and `MERGE_HEAD`);
169
+ useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD` and `MERGE_HEAD`);
170
171
. otherwise, `$GIT_DIR/refs/<name>` if exists;
172
@@ -177,6 +177,16 @@ blobs contained in a commit.
177
. otherwise, `$GIT_DIR/refs/remotes/<name>` if exists;
178
179
. otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists.
180
++
181
+HEAD names the commit your changes in the working tree is based on.
182
+FETCH_HEAD records the branch you fetched from a remote repository
183
+with your last 'git-fetch' invocation.
184
+ORIG_HEAD is created by commands that moves your HEAD in a drastic
185
+way, to record the position of the HEAD before their operation, so that
186
+you can change the tip of the branch back to the state before you ran
187
+them easily.
188
+MERGE_HEAD records the commit(s) you are merging into your branch
189
+when you run 'git-merge'.
190
191
* A ref followed by the suffix '@' with a date specification
192
enclosed in a brace
@@ -289,10 +299,10 @@ notation is used. E.g. "`{caret}r1 r2`" means commits reachable
299
from `r2` but exclude the ones reachable from `r1`.
300
301
This set operation appears so often that there is a shorthand
292
-for it. "`r1..r2`" is equivalent to "`{caret}r1 r2`". It is
293
-the difference of two sets (subtract the set of commits
294
-reachable from `r1` from the set of commits reachable from
295
-`r2`).
302
+for it. When you have two commits `r1` and `r2` (named according
303
+to the syntax explained in SPECIFYING REVISIONS above), you can ask
304
+for commits that are reachable from r2 excluding those that are reachable
305
+from r1 by "`{caret}r1 r2`" and it can be written as "`r1..r2`".
306
307
A similar notation "`r1\...r2`" is called symmetric difference
308
of `r1` and `r2` and is defined as