development/git
development/git
1
0
Fork 0
mirror of https://github.com/git/git synced 2024-08-24 18:26:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation: detached HEAD

Browse source 
Add discussion section to git-checkout documentation and mention
detached HEAD in repository-layout document.

Signed-off-by: Junio C Hamano <junkio@cox.net>
This commit is contained in:
Junio C Hamano 2007-01-17 10:43:50 -08:00
parent 23bfbb815d
commit 5e1a2e8c61
2 changed files with 58 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
Documentation/git-checkout.txt
View file

@ -9,7 +9,7 @@ SYNOPSIS
--------
[verse]
'git-checkout' [-f] [-b <new_branch> [-l]] [-m] [<branch>]
'git-checkout' [-m] [<branch>] <paths>...
'git-checkout' [<branch>] <paths>...
DESCRIPTION
-----------
@ -63,7 +63,57 @@ and mark the resolved paths with `git update-index`.
<branch>::
Branch to checkout; may be any object ID that resolves to a
commit. Defaults to HEAD.
commit. Defaults to HEAD.
+
When this parameter names a non-branch (but still a valid commit object),
your HEAD becomes 'detached'.
Detached HEAD
-------------
It is sometimes useful to be able to 'checkout' a commit that is
not at the tip of one of your branches. The most obvious
example is to check out the commit at a tagged official release
point, like this:
------------
$ git checkout v2.6.18
------------
Earlier versions of git did not allow this and asked you to
create a temporary branch using `-b` option, but starting from
version 1.5.0, the above command 'detaches' your HEAD from the
current branch and directly point at the commit named by the tag
(`v2.6.18` in the above example).
You can use usual git commands while in this state. You can use
`git-reset --hard $othercommit` to further move around, for
example. You can make changes and create a new commit on top of
a detached HEAD. You can even create a merge by using `git
merge $othercommit`.
The state you are in while your HEAD is detached is not recorded
by any branch (which is natural --- you are not on any branch).
What this means is that you can discard your temporary commits
and merges by switching back to an existing branch (e.g. `git
checkout master`), and a later `git prune` or `git gc` would
garbage-collect them.
The command would refuse to switch back to make sure that you do
not discard your temporary state by mistake when your detached
HEAD is not pointed at by any existing ref. If you did want to
save your state (e.g. "I was interested in the fifth commit from
the top of 'master' branch", or "I made two commits to fix minor
bugs while on a detached HEAD" -- and if you do not want to lose
these facts), you can create a new branch and switch to it with
`git checkout -b newbranch` so that you can keep building on
that state, or tag it first so that you can come back to it
later and switch to the branch you wanted to switch to with `git
tag that_state; git checkout master`. On the other hand, if you
did want to discard the temporary state, you can give `-f`
option (e.g. `git checkout -f master`) to override this
behaviour.
EXAMPLES

6
Documentation/repository-layout.txt
View file

@ -91,6 +91,12 @@ HEAD::
'name' does not (yet) exist. In some legacy setups, it is
a symbolic link instead of a symref that points at the current
branch.
+
HEAD can also record a specific commit directly, instead of
being a symref to point at the current branch. Such a state
is often called 'detached HEAD', and almost all commands work
identically as normal. See gitlink:git-checkout[1] for
details.
branches::
A slightly deprecated way to store shorthands to be used