reword the detached head message a little again
[git/git.git] / Documentation / git-checkout.txt
CommitLineData
215a7ad1
JH
1git-checkout(1)
2===============
7fc9d69f
JH
3
4NAME
5----
7bd7f280 6git-checkout - Checkout and switch to a branch
7fc9d69f
JH
7
8SYNOPSIS
9--------
71bb1033 10[verse]
969d326d 11'git-checkout' [-f] [-b <new_branch> [-l]] [-m] [<branch>]
84a978f1 12'git-checkout' [<tree-ish>] <paths>...
7fc9d69f
JH
13
14DESCRIPTION
15-----------
4aaa7027 16
71bb1033 17When <paths> are not given, this command switches branches by
4aaa7027
JH
18updating the index and working tree to reflect the specified
19branch, <branch>, and updating HEAD to be <branch> or, if
71bb1033
JL
20specified, <new_branch>. Using -b will cause <new_branch> to
21be created.
4aaa7027
JH
22
23When <paths> are given, this command does *not* switch
24branches. It updates the named paths in the working tree from
84a978f1
JH
25the index file (i.e. it runs `git-checkout-index -f -u`), or a
26named commit. In
4aaa7027 27this case, `-f` and `-b` options are meaningless and giving
84a978f1
JH
28either of them results in an error. <tree-ish> argument can be
29used to specify a specific tree-ish (i.e. commit, tag or tree)
30to update the index for the given paths before updating the
31working tree.
4aaa7027 32
7fc9d69f
JH
33
34OPTIONS
35-------
0270f7c5 36-f::
71bb1033 37 Force a re-read of everything.
0270f7c5
LAS
38
39-b::
2b1f4247
SP
40 Create a new branch named <new_branch> and start it at
41 <branch>. The new branch name must pass all checks defined
42 by gitlink:git-check-ref-format[1]. Some of these checks
43 may restrict the characters allowed in a branch name.
7fc9d69f 44
969d326d
SP
45-l::
46 Create the new branch's ref log. This activates recording of
47 all changes to made the branch ref, enabling use of date
48 based sha1 expressions such as "<branchname>@{yesterday}".
49
1be0659e 50-m::
71bb1033
JL
51 If you have local modifications to one or more files that
52 are different between the current branch and the branch to
53 which you are switching, the command refuses to switch
54 branches in order to preserve your modifications in context.
55 However, with this option, a three-way merge between the current
1be0659e
JH
56 branch, your working tree contents, and the new branch
57 is done, and you will be on the new branch.
58+
59When a merge conflict happens, the index entries for conflicting
60paths are left unmerged, and you need to resolve the conflicts
61and mark the resolved paths with `git update-index`.
62
0270f7c5
LAS
63<new_branch>::
64 Name for the new branch.
7fc9d69f 65
0270f7c5
LAS
66<branch>::
67 Branch to checkout; may be any object ID that resolves to a
5e1a2e8c
JH
68 commit. Defaults to HEAD.
69+
70When this parameter names a non-branch (but still a valid commit object),
71your HEAD becomes 'detached'.
72
73
74Detached HEAD
75-------------
76
77It is sometimes useful to be able to 'checkout' a commit that is
78not at the tip of one of your branches. The most obvious
79example is to check out the commit at a tagged official release
80point, like this:
81
82------------
83$ git checkout v2.6.18
84------------
85
86Earlier versions of git did not allow this and asked you to
87create a temporary branch using `-b` option, but starting from
88version 1.5.0, the above command 'detaches' your HEAD from the
89current branch and directly point at the commit named by the tag
90(`v2.6.18` in the above example).
91
92You can use usual git commands while in this state. You can use
93`git-reset --hard $othercommit` to further move around, for
94example. You can make changes and create a new commit on top of
95a detached HEAD. You can even create a merge by using `git
96merge $othercommit`.
97
98The state you are in while your HEAD is detached is not recorded
99by any branch (which is natural --- you are not on any branch).
100What this means is that you can discard your temporary commits
101and merges by switching back to an existing branch (e.g. `git
102checkout master`), and a later `git prune` or `git gc` would
103garbage-collect them.
104
105The command would refuse to switch back to make sure that you do
106not discard your temporary state by mistake when your detached
107HEAD is not pointed at by any existing ref. If you did want to
108save your state (e.g. "I was interested in the fifth commit from
109the top of 'master' branch", or "I made two commits to fix minor
110bugs while on a detached HEAD" -- and if you do not want to lose
111these facts), you can create a new branch and switch to it with
112`git checkout -b newbranch` so that you can keep building on
113that state, or tag it first so that you can come back to it
114later and switch to the branch you wanted to switch to with `git
115tag that_state; git checkout master`. On the other hand, if you
116did want to discard the temporary state, you can give `-f`
117option (e.g. `git checkout -f master`) to override this
118behaviour.
7fc9d69f 119
4aaa7027 120
1be0659e
JH
121EXAMPLES
122--------
4aaa7027 123
1be0659e 124. The following sequence checks out the `master` branch, reverts
4aaa7027
JH
125the `Makefile` to two revisions back, deletes hello.c by
126mistake, and gets it back from the index.
1be0659e 127+
4aaa7027 128------------
48aeecdc
SE
129$ git checkout master <1>
130$ git checkout master~2 Makefile <2>
4aaa7027 131$ rm -f hello.c
48aeecdc
SE
132$ git checkout hello.c <3>
133------------
134+
1e2ccd3a
JH
135<1> switch branch
136<2> take out a file out of other commit
48aeecdc 137<3> restore hello.c from HEAD of current branch
1be0659e 138+
48aeecdc
SE
139If you have an unfortunate branch that is named `hello.c`, this
140step would be confused as an instruction to switch to that branch.
141You should instead write:
1be0659e 142+
4aaa7027
JH
143------------
144$ git checkout -- hello.c
145------------
146
1be0659e 147. After working in a wrong branch, switching to the correct
71bb1033 148branch would be done using:
1be0659e
JH
149+
150------------
151$ git checkout mytopic
152------------
153+
154However, your "wrong" branch and correct "mytopic" branch may
155differ in files that you have locally modified, in which case,
156the above checkout would fail like this:
157+
158------------
159$ git checkout mytopic
160fatal: Entry 'frotz' not uptodate. Cannot merge.
161------------
162+
163You can give the `-m` flag to the command, which would try a
164three-way merge:
165+
166------------
167$ git checkout -m mytopic
168Auto-merging frotz
169------------
170+
171After this three-way merge, the local modifications are _not_
172registered in your index file, so `git diff` would show you what
173changes you made since the tip of the new branch.
174
175. When a merge conflict happens during switching branches with
176the `-m` option, you would see something like this:
177+
178------------
179$ git checkout -m mytopic
180Auto-merging frotz
181merge: warning: conflicts during merge
182ERROR: Merge conflict in frotz
183fatal: merge program failed
184------------
185+
186At this point, `git diff` shows the changes cleanly merged as in
187the previous example, as well as the changes in the conflicted
188files. Edit and resolve the conflict and mark it resolved with
189`git update-index` as usual:
190+
191------------
192$ edit frotz
193$ git update-index frotz
194------------
195
4aaa7027 196
7fc9d69f
JH
197Author
198------
199Written by Linus Torvalds <torvalds@osdl.org>
200
201Documentation
202--------------
203Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
204
205GIT
206---
a7154e91 207Part of the gitlink:git[7] suite
7fc9d69f 208