Attempt to improve git-rebase lead-in description.
[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]
6124aee5 11'git-checkout' [-q] [-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-------
6124aee5
NP
36-q::
37 Quiet, supress feedback messages.
38
0270f7c5 39-f::
71bb1033 40 Force a re-read of everything.
0270f7c5
LAS
41
42-b::
2b1f4247
SP
43 Create a new branch named <new_branch> and start it at
44 <branch>. The new branch name must pass all checks defined
45 by gitlink:git-check-ref-format[1]. Some of these checks
46 may restrict the characters allowed in a branch name.
7fc9d69f 47
969d326d
SP
48-l::
49 Create the new branch's ref log. This activates recording of
50 all changes to made the branch ref, enabling use of date
51 based sha1 expressions such as "<branchname>@{yesterday}".
52
1be0659e 53-m::
71bb1033
JL
54 If you have local modifications to one or more files that
55 are different between the current branch and the branch to
56 which you are switching, the command refuses to switch
57 branches in order to preserve your modifications in context.
58 However, with this option, a three-way merge between the current
1be0659e
JH
59 branch, your working tree contents, and the new branch
60 is done, and you will be on the new branch.
61+
62When a merge conflict happens, the index entries for conflicting
63paths are left unmerged, and you need to resolve the conflicts
64and mark the resolved paths with `git update-index`.
65
0270f7c5
LAS
66<new_branch>::
67 Name for the new branch.
7fc9d69f 68
0270f7c5
LAS
69<branch>::
70 Branch to checkout; may be any object ID that resolves to a
5e1a2e8c
JH
71 commit. Defaults to HEAD.
72+
73When this parameter names a non-branch (but still a valid commit object),
74your HEAD becomes 'detached'.
75
76
77Detached HEAD
78-------------
79
80It is sometimes useful to be able to 'checkout' a commit that is
81not at the tip of one of your branches. The most obvious
82example is to check out the commit at a tagged official release
83point, like this:
84
85------------
86$ git checkout v2.6.18
87------------
88
89Earlier versions of git did not allow this and asked you to
90create a temporary branch using `-b` option, but starting from
91version 1.5.0, the above command 'detaches' your HEAD from the
92current branch and directly point at the commit named by the tag
93(`v2.6.18` in the above example).
94
95You can use usual git commands while in this state. You can use
96`git-reset --hard $othercommit` to further move around, for
97example. You can make changes and create a new commit on top of
98a detached HEAD. You can even create a merge by using `git
99merge $othercommit`.
100
101The state you are in while your HEAD is detached is not recorded
102by any branch (which is natural --- you are not on any branch).
103What this means is that you can discard your temporary commits
104and merges by switching back to an existing branch (e.g. `git
105checkout master`), and a later `git prune` or `git gc` would
cec8d146
JH
106garbage-collect them. If you did this by mistake, you can ask
107the reflog for HEAD where you were, e.g.
108
109------------
110$ git log -g -2 HEAD
111------------
7fc9d69f 112
4aaa7027 113
1be0659e
JH
114EXAMPLES
115--------
4aaa7027 116
1be0659e 117. The following sequence checks out the `master` branch, reverts
4aaa7027
JH
118the `Makefile` to two revisions back, deletes hello.c by
119mistake, and gets it back from the index.
1be0659e 120+
4aaa7027 121------------
48aeecdc
SE
122$ git checkout master <1>
123$ git checkout master~2 Makefile <2>
4aaa7027 124$ rm -f hello.c
48aeecdc
SE
125$ git checkout hello.c <3>
126------------
127+
1e2ccd3a
JH
128<1> switch branch
129<2> take out a file out of other commit
48aeecdc 130<3> restore hello.c from HEAD of current branch
1be0659e 131+
48aeecdc
SE
132If you have an unfortunate branch that is named `hello.c`, this
133step would be confused as an instruction to switch to that branch.
134You should instead write:
1be0659e 135+
4aaa7027
JH
136------------
137$ git checkout -- hello.c
138------------
139
1be0659e 140. After working in a wrong branch, switching to the correct
71bb1033 141branch would be done using:
1be0659e
JH
142+
143------------
144$ git checkout mytopic
145------------
146+
147However, your "wrong" branch and correct "mytopic" branch may
148differ in files that you have locally modified, in which case,
149the above checkout would fail like this:
150+
151------------
152$ git checkout mytopic
153fatal: Entry 'frotz' not uptodate. Cannot merge.
154------------
155+
156You can give the `-m` flag to the command, which would try a
157three-way merge:
158+
159------------
160$ git checkout -m mytopic
161Auto-merging frotz
162------------
163+
164After this three-way merge, the local modifications are _not_
165registered in your index file, so `git diff` would show you what
166changes you made since the tip of the new branch.
167
168. When a merge conflict happens during switching branches with
169the `-m` option, you would see something like this:
170+
171------------
172$ git checkout -m mytopic
173Auto-merging frotz
174merge: warning: conflicts during merge
175ERROR: Merge conflict in frotz
176fatal: merge program failed
177------------
178+
179At this point, `git diff` shows the changes cleanly merged as in
180the previous example, as well as the changes in the conflicted
181files. Edit and resolve the conflict and mark it resolved with
182`git update-index` as usual:
183+
184------------
185$ edit frotz
186$ git update-index frotz
187------------
188
4aaa7027 189
7fc9d69f
JH
190Author
191------
192Written by Linus Torvalds <torvalds@osdl.org>
193
194Documentation
195--------------
196Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
197
198GIT
199---
a7154e91 200Part of the gitlink:git[7] suite
7fc9d69f 201