dir.c: squelch false uninitialized memory warning
[git/git.git] / Documentation / git-checkout.txt
CommitLineData
215a7ad1
JH
1git-checkout(1)
2===============
7fc9d69f
JH
3
4NAME
5----
76ce9462 6git-checkout - Checkout a branch or paths to the working tree
7fc9d69f
JH
7
8SYNOPSIS
9--------
71bb1033 10[verse]
76cfadfc 11'git checkout' [-q] [-f] [-m] [<branch>]
02ac9837 12'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
eac5a401 13'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
4f353658 14'git checkout' --patch [<tree-ish>] [--] [<paths>...]
7fc9d69f
JH
15
16DESCRIPTION
17-----------
b831deda
JN
18Updates files in the working tree to match the version in the index
19or the specified tree. If no paths are given, 'git checkout' will
20also update `HEAD` to set the specified branch as the current
76cfadfc 21branch.
4aaa7027 22
b831deda 23'git checkout' [<branch>]::
02ac9837 24'git checkout' -b|-B <new_branch> [<start point>]::
4aaa7027 25
b831deda
JN
26 This form switches branches by updating the index, working
27 tree, and HEAD to reflect the specified branch.
c5b41519 28+
b831deda
JN
29If `-b` is given, a new branch is created as if linkgit:git-branch[1]
30were called and then checked out; in this case you can
31use the `--track` or `--no-track` options, which will be passed to
32'git branch'. As a convenience, `--track` without `-b` implies branch
33creation; see the description of `--track` below.
02ac9837
TRC
34+
35If `-B` is given, <new_branch> is created if it doesn't exist; otherwise, it
36is reset. This is the transactional equivalent of
37+
38------------
39$ git branch -f <branch> [<start point>]
40$ git checkout <branch>
41------------
42+
43that is to say, the branch is not reset/created unless "git checkout" is
44successful.
bb0ceb62 45
b831deda 46'git checkout' [--patch] [<tree-ish>] [--] <pathspec>...::
4aaa7027 47
b831deda 48 When <paths> or `--patch` are given, 'git checkout' *not* switch
c5b41519 49 branches. It updates the named paths in the working tree from
b831deda 50 the index file or from a named <tree-ish> (most often a commit). In
c5b41519
JN
51 this case, the `-b` and `--track` options are meaningless and giving
52 either of them results in an error. The <tree-ish> argument can be
53 used to specify a specific tree-ish (i.e. commit, tag or tree)
54 to update the index for the given paths before updating the
55 working tree.
56+
b831deda
JN
57The index may contain unmerged entries because of a previous failed merge.
58By default, if you try to check out such an entry from the index, the
db941099 59checkout operation will fail and nothing will be checked out.
b831deda 60Using `-f` will ignore these unmerged entries. The contents from a
38901a48 61specific side of the merge can be checked out of the index by
b831deda
JN
62using `--ours` or `--theirs`. With `-m`, changes made to the working tree
63file can be discarded to re-create the original conflicted merge result.
7fc9d69f
JH
64
65OPTIONS
66-------
6124aee5 67-q::
f7aec129 68--quiet::
2be7fcb4 69 Quiet, suppress feedback messages.
6124aee5 70
0270f7c5 71-f::
f7aec129 72--force::
db941099
JH
73 When switching branches, proceed even if the index or the
74 working tree differs from HEAD. This is used to throw away
75 local changes.
76+
77When checking out paths from the index, do not fail upon unmerged
78entries; instead, unmerged entries are ignored.
0270f7c5 79
38901a48
JH
80--ours::
81--theirs::
82 When checking out paths from the index, check out stage #2
83 ('ours') or #3 ('theirs') for unmerged paths.
0270f7c5
LAS
84
85-b::
2b1f4247 86 Create a new branch named <new_branch> and start it at
76cfadfc 87 <start_point>; see linkgit:git-branch[1] for details.
7fc9d69f 88
02ac9837
TRC
89-B::
90 Creates the branch <new_branch> and start it at <start_point>;
91 if it already exists, then reset it to <start_point>. This is
92 equivalent to running "git branch" with "-f"; see
93 linkgit:git-branch[1] for details.
94
3240240f
SB
95-t::
96--track::
26d22dc6
JK
97 When creating a new branch, set up "upstream" configuration. See
98 "--track" in linkgit:git-branch[1] for details.
bb0ceb62 99+
c7cb12b8
MG
100If no '-b' option is given, the name of the new branch will be
101derived from the remote branch. If "remotes/" or "refs/remotes/"
102is prefixed it is stripped away, and then the part up to the
9188ed89
AR
103next slash (which would be the nickname of the remote) is removed.
104This would tell us to use "hack" as the local branch when branching
105off of "origin/hack" (or "remotes/origin/hack", or even
106"refs/remotes/origin/hack"). If the given name has no slash, or the above
107guessing results in an empty name, the guessing is aborted. You can
971e8352 108explicitly give a name with '-b' in such a case.
0746d19a
PB
109
110--no-track::
167d7445 111 Do not set up "upstream" configuration, even if the
70e96647 112 branch.autosetupmerge configuration variable is true.
0746d19a 113
969d326d 114-l::
26d22dc6
JK
115 Create the new branch's reflog; see linkgit:git-branch[1] for
116 details.
969d326d 117
9db5ebf4 118--orphan::
feb98d13
EM
119 Create a new 'orphan' branch, named <new_branch>, started from
120 <start_point> and switch to it. The first commit made on this
121 new branch will have no parents and it will be the root of a new
122 history totally disconnected from all the other branches and
123 commits.
9db5ebf4 124+
feb98d13
EM
125The index and the working tree are adjusted as if you had previously run
126"git checkout <start_point>". This allows you to start a new history
127that records a set of paths similar to <start_point> by easily running
128"git commit -a" to make the root commit.
9db5ebf4 129+
feb98d13
EM
130This can be useful when you want to publish the tree from a commit
131without exposing its full history. You might want to do this to publish
132an open source branch of a project whose current tree is "clean", but
133whose full history contains proprietary or otherwise encumbered bits of
134code.
135+
136If you want to start a disconnected history that records a set of paths
137that is totally different from the one of <start_point>, then you should
138clear the index and the working tree right after creating the orphan
139branch by running "git rm -rf ." from the top level of the working tree.
140Afterwards you will be ready to prepare your new files, repopulating the
141working tree, by copying them from elsewhere, extracting a tarball, etc.
9db5ebf4 142
1be0659e 143-m::
eac5a401 144--merge::
0cf8581e
JH
145 When switching branches,
146 if you have local modifications to one or more files that
71bb1033
JL
147 are different between the current branch and the branch to
148 which you are switching, the command refuses to switch
149 branches in order to preserve your modifications in context.
150 However, with this option, a three-way merge between the current
1be0659e
JH
151 branch, your working tree contents, and the new branch
152 is done, and you will be on the new branch.
153+
154When a merge conflict happens, the index entries for conflicting
155paths are left unmerged, and you need to resolve the conflicts
d7f078b8
SP
156and mark the resolved paths with `git add` (or `git rm` if the merge
157should result in deletion of the path).
0cf8581e
JH
158+
159When checking out paths from the index, this option lets you recreate
160the conflicted merge in the specified paths.
1be0659e 161
eac5a401
JH
162--conflict=<style>::
163 The same as --merge option above, but changes the way the
164 conflicting hunks are presented, overriding the
165 merge.conflictstyle configuration variable. Possible values are
166 "merge" (default) and "diff3" (in addition to what is shown by
167 "merge" style, shows the original contents).
1be0659e 168
4f353658
TR
169-p::
170--patch::
171 Interactively select hunks in the difference between the
172 <tree-ish> (or the index, if unspecified) and the working
173 tree. The chosen hunks are then applied in reverse to the
174 working tree (and if a <tree-ish> was specified, the index).
175+
176This means that you can use `git checkout -p` to selectively discard
177edits from your current working tree.
178
0270f7c5 179<branch>::
0808723b
JK
180 Branch to checkout; if it refers to a branch (i.e., a name that,
181 when prepended with "refs/heads/", is a valid ref), then that
182 branch is checked out. Otherwise, if it refers to a valid
183 commit, your HEAD becomes "detached" and you are no longer on
184 any branch (see below for details).
696acf45 185+
dcb11263 186As a special case, the `"@\{-N\}"` syntax for the N-th last branch
696acf45 187checks out the branch (instead of detaching). You may also specify
dcb11263 188`-` which is synonymous with `"@\{-1\}"`.
873c3472 189+
b9190e79 190As a further special case, you may use `"A\...B"` as a shortcut for the
873c3472
MG
191merge base of `A` and `B` if there is exactly one merge base. You can
192leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
5e1a2e8c 193
76cfadfc
JK
194<new_branch>::
195 Name for the new branch.
196
197<start_point>::
198 The name of a commit at which to start the new branch; see
199 linkgit:git-branch[1] for details. Defaults to HEAD.
200
201<tree-ish>::
202 Tree to checkout from (when paths are given). If not specified,
203 the index will be used.
204
205
5e1a2e8c
JH
206
207Detached HEAD
208-------------
209
210It is sometimes useful to be able to 'checkout' a commit that is
211not at the tip of one of your branches. The most obvious
212example is to check out the commit at a tagged official release
213point, like this:
214
215------------
216$ git checkout v2.6.18
217------------
218
219Earlier versions of git did not allow this and asked you to
c7cb12b8 220create a temporary branch using the `-b` option, but starting from
5e1a2e8c 221version 1.5.0, the above command 'detaches' your HEAD from the
c7cb12b8
MG
222current branch and directly points at the commit named by the tag
223(`v2.6.18` in the example above).
5e1a2e8c 224
c7cb12b8 225You can use all git commands while in this state. You can use
b1889c36 226`git reset --hard $othercommit` to further move around, for
5e1a2e8c
JH
227example. You can make changes and create a new commit on top of
228a detached HEAD. You can even create a merge by using `git
229merge $othercommit`.
230
231The state you are in while your HEAD is detached is not recorded
232by any branch (which is natural --- you are not on any branch).
233What this means is that you can discard your temporary commits
234and merges by switching back to an existing branch (e.g. `git
235checkout master`), and a later `git prune` or `git gc` would
cec8d146
JH
236garbage-collect them. If you did this by mistake, you can ask
237the reflog for HEAD where you were, e.g.
238
239------------
240$ git log -g -2 HEAD
241------------
7fc9d69f 242
4aaa7027 243
1be0659e
JH
244EXAMPLES
245--------
4aaa7027 246
1be0659e 247. The following sequence checks out the `master` branch, reverts
4aaa7027
JH
248the `Makefile` to two revisions back, deletes hello.c by
249mistake, and gets it back from the index.
1be0659e 250+
4aaa7027 251------------
48aeecdc
SE
252$ git checkout master <1>
253$ git checkout master~2 Makefile <2>
4aaa7027 254$ rm -f hello.c
48aeecdc
SE
255$ git checkout hello.c <3>
256------------
257+
1e2ccd3a 258<1> switch branch
c7cb12b8 259<2> take a file out of another commit
ce8936c3 260<3> restore hello.c from the index
1be0659e 261+
48aeecdc
SE
262If you have an unfortunate branch that is named `hello.c`, this
263step would be confused as an instruction to switch to that branch.
264You should instead write:
1be0659e 265+
4aaa7027
JH
266------------
267$ git checkout -- hello.c
268------------
269
c7cb12b8 270. After working in the wrong branch, switching to the correct
71bb1033 271branch would be done using:
1be0659e
JH
272+
273------------
274$ git checkout mytopic
275------------
276+
277However, your "wrong" branch and correct "mytopic" branch may
c7cb12b8 278differ in files that you have modified locally, in which case
1be0659e
JH
279the above checkout would fail like this:
280+
281------------
282$ git checkout mytopic
142183d0 283error: You have local changes to 'frotz'; not switching branches.
1be0659e
JH
284------------
285+
286You can give the `-m` flag to the command, which would try a
287three-way merge:
288+
289------------
290$ git checkout -m mytopic
291Auto-merging frotz
292------------
293+
294After this three-way merge, the local modifications are _not_
295registered in your index file, so `git diff` would show you what
296changes you made since the tip of the new branch.
297
298. When a merge conflict happens during switching branches with
299the `-m` option, you would see something like this:
300+
301------------
302$ git checkout -m mytopic
303Auto-merging frotz
1be0659e
JH
304ERROR: Merge conflict in frotz
305fatal: merge program failed
306------------
307+
308At this point, `git diff` shows the changes cleanly merged as in
309the previous example, as well as the changes in the conflicted
310files. Edit and resolve the conflict and mark it resolved with
d7f078b8 311`git add` as usual:
1be0659e
JH
312+
313------------
314$ edit frotz
d7f078b8 315$ git add frotz
1be0659e
JH
316------------
317
4aaa7027 318
7fc9d69f
JH
319Author
320------
321Written by Linus Torvalds <torvalds@osdl.org>
322
323Documentation
324--------------
325Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
326
327GIT
328---
9e1f0a85 329Part of the linkgit:git[1] suite