user-manual: detached HEAD
Add a brief mention of detached HEADs and .git/HEAD. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <junkio@cox.net>
J. Bruce Fields committed
Apr 16, 2007 at 00:37 UTC
72a76c955bcbe6370db7dc34b962851de189e650
1 file changed
+42
-2
Documentation/user-manual.txt
+42
-2
@@ -495,8 +495,48 @@ git checkout -b <new> <start-point>::
495
create a new branch <new> referencing <start-point>, and
496
check it out.
497
498
-It is also useful to know that the special symbol "HEAD" can always
499
-be used to refer to the current branch.
498
+The special symbol "HEAD" can always be used to refer to the current
499
+branch. In fact, git uses a file named "HEAD" in the .git directory to
500
+remember which branch is current:
501
+
502
+------------------------------------------------
503
+$ cat .git/HEAD
504
+ref: refs/heads/master
505
+------------------------------------------------
506
+
507
+Examining an old version without creating a new branch
508
+------------------------------------------------------
509
+
510
+The git-checkout command normally expects a branch head, but will also
511
+accept an arbitrary commit; for example, you can check out the commit
512
+referenced by a tag:
513
+
514
+------------------------------------------------
515
+$ git checkout v2.6.17
516
+Note: moving to "v2.6.17" which isn't a local branch
517
+If you want to create a new branch from this checkout, you may do so
518
+(now or later) by using -b with the checkout command again. Example:
519
+ git checkout -b <new_branch_name>
520
+HEAD is now at 427abfa... Linux v2.6.17
521
+------------------------------------------------
522
+
523
+The HEAD then refers to the SHA1 of the commit instead of to a branch,
524
+and git branch shows that you are no longer on a branch:
525
+
526
+------------------------------------------------
527
+$ cat .git/HEAD
528
+427abfa28afedffadfca9dd8b067eb6d36bac53f
529
+git branch
530
+* (no branch)
531
+ master
532
+------------------------------------------------
533
+
534
+In this case we say that the HEAD is "detached".
535
+
536
+This can be an easy way to check out a particular version without having
537
+to make up a name for a new branch. However, keep in mind that when you
538
+switch away from the (for example, by checking out something else), you
539
+can lose track of what the HEAD used to point to.
540
541
Examining branches from a remote repository
542
-------------------------------------------