Revert "Convert output messages in merge-recursive to past tense."
[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]
bb0ceb62 11'git checkout' [-q] [-f] [--track | --no-track] [-b <new_branch> [-l]] [-m] [<branch>]
b302ddd2 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 20specified, <new_branch>. Using -b will cause <new_branch> to
0746d19a
PB
21be created; in this case you can use the --track or --no-track
22options, which will be passed to `git branch`.
4aaa7027 23
bb0ceb62
JS
24As a convenience, --track will default to create a branch whose
25name is constructed from the specified branch name by stripping
26the first namespace level.
27
4aaa7027
JH
28When <paths> are given, this command does *not* switch
29branches. It updates the named paths in the working tree from
b1889c36 30the index file (i.e. it runs `git checkout-index -f -u`), or
40c8279f
BF
31from a named commit. In
32this case, the `-f` and `-b` options are meaningless and giving
84a978f1
JH
33either of them results in an error. <tree-ish> argument can be
34used to specify a specific tree-ish (i.e. commit, tag or tree)
35to update the index for the given paths before updating the
36working tree.
4aaa7027 37
7fc9d69f
JH
38
39OPTIONS
40-------
6124aee5 41-q::
2be7fcb4 42 Quiet, suppress feedback messages.
6124aee5 43
0270f7c5 44-f::
40c8279f
BF
45 Proceed even if the index or the working tree differs
46 from HEAD. This is used to throw away local changes.
0270f7c5
LAS
47
48-b::
2b1f4247
SP
49 Create a new branch named <new_branch> and start it at
50 <branch>. The new branch name must pass all checks defined
5162e697 51 by linkgit:git-check-ref-format[1]. Some of these checks
2b1f4247 52 may restrict the characters allowed in a branch name.
7fc9d69f 53
3240240f
SB
54-t::
55--track::
ba020ef5 56 When creating a new branch, set up configuration so that 'git-pull'
572fc81d
JS
57 will automatically retrieve data from the start point, which must be
58 a branch. Use this if you always pull from the same upstream branch
59 into the new branch, and if you don't want to use "git pull
60 <repository> <refspec>" explicitly. This behavior is the default
61 when the start point is a remote branch. Set the
62 branch.autosetupmerge configuration variable to `false` if you want
ba020ef5 63 'git-checkout' and 'git-branch' to always behave as if '--no-track' were
572fc81d
JS
64 given. Set it to `always` if you want this behavior when the
65 start-point is either a local or remote branch.
bb0ceb62
JS
66+
67If no '-b' option was given, a name will be made up for you, by stripping
68the part up to the first slash of the tracked branch. For example, if you
69called 'git checkout --track origin/next', the branch name will be 'next'.
0746d19a
PB
70
71--no-track::
572fc81d 72 Ignore the branch.autosetupmerge configuration variable.
0746d19a 73
969d326d 74-l::
792d2370
JK
75 Create the new branch's reflog. This activates recording of
76 all changes made to the branch ref, enabling use of date
967506bb 77 based sha1 expressions such as "<branchname>@\{yesterday}".
969d326d 78
1be0659e 79-m::
71bb1033
JL
80 If you have local modifications to one or more files that
81 are different between the current branch and the branch to
82 which you are switching, the command refuses to switch
83 branches in order to preserve your modifications in context.
84 However, with this option, a three-way merge between the current
1be0659e
JH
85 branch, your working tree contents, and the new branch
86 is done, and you will be on the new branch.
87+
88When a merge conflict happens, the index entries for conflicting
89paths are left unmerged, and you need to resolve the conflicts
d7f078b8
SP
90and mark the resolved paths with `git add` (or `git rm` if the merge
91should result in deletion of the path).
1be0659e 92
0270f7c5
LAS
93<new_branch>::
94 Name for the new branch.
7fc9d69f 95
0270f7c5
LAS
96<branch>::
97 Branch to checkout; may be any object ID that resolves to a
5e1a2e8c
JH
98 commit. Defaults to HEAD.
99+
100When this parameter names a non-branch (but still a valid commit object),
101your HEAD becomes 'detached'.
102
103
104Detached HEAD
105-------------
106
107It is sometimes useful to be able to 'checkout' a commit that is
108not at the tip of one of your branches. The most obvious
109example is to check out the commit at a tagged official release
110point, like this:
111
112------------
113$ git checkout v2.6.18
114------------
115
116Earlier versions of git did not allow this and asked you to
117create a temporary branch using `-b` option, but starting from
118version 1.5.0, the above command 'detaches' your HEAD from the
119current branch and directly point at the commit named by the tag
120(`v2.6.18` in the above example).
121
122You can use usual git commands while in this state. You can use
b1889c36 123`git reset --hard $othercommit` to further move around, for
5e1a2e8c
JH
124example. You can make changes and create a new commit on top of
125a detached HEAD. You can even create a merge by using `git
126merge $othercommit`.
127
128The state you are in while your HEAD is detached is not recorded
129by any branch (which is natural --- you are not on any branch).
130What this means is that you can discard your temporary commits
131and merges by switching back to an existing branch (e.g. `git
132checkout master`), and a later `git prune` or `git gc` would
cec8d146
JH
133garbage-collect them. If you did this by mistake, you can ask
134the reflog for HEAD where you were, e.g.
135
136------------
137$ git log -g -2 HEAD
138------------
7fc9d69f 139
4aaa7027 140
1be0659e
JH
141EXAMPLES
142--------
4aaa7027 143
1be0659e 144. The following sequence checks out the `master` branch, reverts
4aaa7027
JH
145the `Makefile` to two revisions back, deletes hello.c by
146mistake, and gets it back from the index.
1be0659e 147+
4aaa7027 148------------
48aeecdc
SE
149$ git checkout master <1>
150$ git checkout master~2 Makefile <2>
4aaa7027 151$ rm -f hello.c
48aeecdc
SE
152$ git checkout hello.c <3>
153------------
154+
1e2ccd3a
JH
155<1> switch branch
156<2> take out a file out of other commit
48aeecdc 157<3> restore hello.c from HEAD of current branch
1be0659e 158+
48aeecdc
SE
159If you have an unfortunate branch that is named `hello.c`, this
160step would be confused as an instruction to switch to that branch.
161You should instead write:
1be0659e 162+
4aaa7027
JH
163------------
164$ git checkout -- hello.c
165------------
166
1be0659e 167. After working in a wrong branch, switching to the correct
71bb1033 168branch would be done using:
1be0659e
JH
169+
170------------
171$ git checkout mytopic
172------------
173+
174However, your "wrong" branch and correct "mytopic" branch may
175differ in files that you have locally modified, in which case,
176the above checkout would fail like this:
177+
178------------
179$ git checkout mytopic
180fatal: Entry 'frotz' not uptodate. Cannot merge.
181------------
182+
183You can give the `-m` flag to the command, which would try a
184three-way merge:
185+
186------------
187$ git checkout -m mytopic
188Auto-merging frotz
189------------
190+
191After this three-way merge, the local modifications are _not_
192registered in your index file, so `git diff` would show you what
193changes you made since the tip of the new branch.
194
195. When a merge conflict happens during switching branches with
196the `-m` option, you would see something like this:
197+
198------------
199$ git checkout -m mytopic
200Auto-merging frotz
201merge: warning: conflicts during merge
202ERROR: Merge conflict in frotz
203fatal: merge program failed
204------------
205+
206At this point, `git diff` shows the changes cleanly merged as in
207the previous example, as well as the changes in the conflicted
208files. Edit and resolve the conflict and mark it resolved with
d7f078b8 209`git add` as usual:
1be0659e
JH
210+
211------------
212$ edit frotz
d7f078b8 213$ git add frotz
1be0659e
JH
214------------
215
4aaa7027 216
7fc9d69f
JH
217Author
218------
219Written by Linus Torvalds <torvalds@osdl.org>
220
221Documentation
222--------------
223Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
224
225GIT
226---
9e1f0a85 227Part of the linkgit:git[1] suite