@matheusbsbs / matheus-bagliano / commits / 5e1a2e8c61
Fork 0

Documentation: detached HEAD

Add discussion section to git-checkout documentation and mention detached HEAD in repository-layout document. Signed-off-by: Junio C Hamano <junkio@cox.net>

Junio C Hamano committed Jan 17, 2007 at 10:43 UTC 5e1a2e8c61b31410fd0c2e5a67c45bf6b373f4c3
2 files changed +58 -2
Documentation/git-checkout.txt
+52 -2
@@ -9,7 +9,7 @@ SYNOPSIS
9 --------
10 [verse]
11 'git-checkout' [-f] [-b <new_branch> [-l]] [-m] [<branch>]
12 -'git-checkout' [-m] [<branch>] <paths>...
12 +'git-checkout' [<branch>] <paths>...
13
14 DESCRIPTION
15 -----------
@@ -63,7 +63,57 @@ and mark the resolved paths with `git update-index`.
63
64 <branch>::
65 Branch to checkout; may be any object ID that resolves to a
66 - commit. Defaults to HEAD.
66 + commit. Defaults to HEAD.
67 ++
68 +When this parameter names a non-branch (but still a valid commit object),
69 +your HEAD becomes 'detached'.
70 +
71 +
72 +Detached HEAD
73 +-------------
74 +
75 +It is sometimes useful to be able to 'checkout' a commit that is
76 +not at the tip of one of your branches. The most obvious
77 +example is to check out the commit at a tagged official release
78 +point, like this:
79 +
80 +------------
81 +$ git checkout v2.6.18
82 +------------
83 +
84 +Earlier versions of git did not allow this and asked you to
85 +create a temporary branch using `-b` option, but starting from
86 +version 1.5.0, the above command 'detaches' your HEAD from the
87 +current branch and directly point at the commit named by the tag
88 +(`v2.6.18` in the above example).
89 +
90 +You can use usual git commands while in this state. You can use
91 +`git-reset --hard $othercommit` to further move around, for
92 +example. You can make changes and create a new commit on top of
93 +a detached HEAD. You can even create a merge by using `git
94 +merge $othercommit`.
95 +
96 +The state you are in while your HEAD is detached is not recorded
97 +by any branch (which is natural --- you are not on any branch).
98 +What this means is that you can discard your temporary commits
99 +and merges by switching back to an existing branch (e.g. `git
100 +checkout master`), and a later `git prune` or `git gc` would
101 +garbage-collect them.
102 +
103 +The command would refuse to switch back to make sure that you do
104 +not discard your temporary state by mistake when your detached
105 +HEAD is not pointed at by any existing ref. If you did want to
106 +save your state (e.g. "I was interested in the fifth commit from
107 +the top of 'master' branch", or "I made two commits to fix minor
108 +bugs while on a detached HEAD" -- and if you do not want to lose
109 +these facts), you can create a new branch and switch to it with
110 +`git checkout -b newbranch` so that you can keep building on
111 +that state, or tag it first so that you can come back to it
112 +later and switch to the branch you wanted to switch to with `git
113 +tag that_state; git checkout master`. On the other hand, if you
114 +did want to discard the temporary state, you can give `-f`
115 +option (e.g. `git checkout -f master`) to override this
116 +behaviour.
117
118
119 EXAMPLES
Documentation/repository-layout.txt
+6
@@ -91,6 +91,12 @@ HEAD::
91 'name' does not (yet) exist. In some legacy setups, it is
92 a symbolic link instead of a symref that points at the current
93 branch.
94 ++
95 +HEAD can also record a specific commit directly, instead of
96 +being a symref to point at the current branch. Such a state
97 +is often called 'detached HEAD', and almost all commands work
98 +identically as normal. See gitlink:git-checkout[1] for
99 +details.
100
101 branches::
102 A slightly deprecated way to store shorthands to be used