Commit | Line | Data |
---|---|---|
215a7ad1 JH |
1 | git-checkout(1) |
2 | =============== | |
7fc9d69f JH |
3 | |
4 | NAME | |
5 | ---- | |
7bd7f280 | 6 | git-checkout - Checkout and switch to a branch |
7fc9d69f JH |
7 | |
8 | SYNOPSIS | |
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 | |
14 | DESCRIPTION | |
15 | ----------- | |
4aaa7027 | 16 | |
71bb1033 | 17 | When <paths> are not given, this command switches branches by |
4aaa7027 JH |
18 | updating the index and working tree to reflect the specified |
19 | branch, <branch>, and updating HEAD to be <branch> or, if | |
71bb1033 JL |
20 | specified, <new_branch>. Using -b will cause <new_branch> to |
21 | be created. | |
4aaa7027 JH |
22 | |
23 | When <paths> are given, this command does *not* switch | |
24 | branches. It updates the named paths in the working tree from | |
84a978f1 JH |
25 | the index file (i.e. it runs `git-checkout-index -f -u`), or a |
26 | named commit. In | |
4aaa7027 | 27 | this case, `-f` and `-b` options are meaningless and giving |
84a978f1 JH |
28 | either of them results in an error. <tree-ish> argument can be |
29 | used to specify a specific tree-ish (i.e. commit, tag or tree) | |
30 | to update the index for the given paths before updating the | |
31 | working tree. | |
4aaa7027 | 32 | |
7fc9d69f JH |
33 | |
34 | OPTIONS | |
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 | + | |
59 | When a merge conflict happens, the index entries for conflicting | |
60 | paths are left unmerged, and you need to resolve the conflicts | |
61 | and 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 | + | |
70 | When this parameter names a non-branch (but still a valid commit object), | |
71 | your HEAD becomes 'detached'. | |
72 | ||
73 | ||
74 | Detached HEAD | |
75 | ------------- | |
76 | ||
77 | It is sometimes useful to be able to 'checkout' a commit that is | |
78 | not at the tip of one of your branches. The most obvious | |
79 | example is to check out the commit at a tagged official release | |
80 | point, like this: | |
81 | ||
82 | ------------ | |
83 | $ git checkout v2.6.18 | |
84 | ------------ | |
85 | ||
86 | Earlier versions of git did not allow this and asked you to | |
87 | create a temporary branch using `-b` option, but starting from | |
88 | version 1.5.0, the above command 'detaches' your HEAD from the | |
89 | current branch and directly point at the commit named by the tag | |
90 | (`v2.6.18` in the above example). | |
91 | ||
92 | You can use usual git commands while in this state. You can use | |
93 | `git-reset --hard $othercommit` to further move around, for | |
94 | example. You can make changes and create a new commit on top of | |
95 | a detached HEAD. You can even create a merge by using `git | |
96 | merge $othercommit`. | |
97 | ||
98 | The state you are in while your HEAD is detached is not recorded | |
99 | by any branch (which is natural --- you are not on any branch). | |
100 | What this means is that you can discard your temporary commits | |
101 | and merges by switching back to an existing branch (e.g. `git | |
102 | checkout master`), and a later `git prune` or `git gc` would | |
103 | garbage-collect them. | |
104 | ||
105 | The command would refuse to switch back to make sure that you do | |
106 | not discard your temporary state by mistake when your detached | |
107 | HEAD is not pointed at by any existing ref. If you did want to | |
108 | save your state (e.g. "I was interested in the fifth commit from | |
109 | the top of 'master' branch", or "I made two commits to fix minor | |
110 | bugs while on a detached HEAD" -- and if you do not want to lose | |
111 | these facts), you can create a new branch and switch to it with | |
112 | `git checkout -b newbranch` so that you can keep building on | |
113 | that state, or tag it first so that you can come back to it | |
114 | later and switch to the branch you wanted to switch to with `git | |
115 | tag that_state; git checkout master`. On the other hand, if you | |
116 | did want to discard the temporary state, you can give `-f` | |
117 | option (e.g. `git checkout -f master`) to override this | |
118 | behaviour. | |
7fc9d69f | 119 | |
4aaa7027 | 120 | |
1be0659e JH |
121 | EXAMPLES |
122 | -------- | |
4aaa7027 | 123 | |
1be0659e | 124 | . The following sequence checks out the `master` branch, reverts |
4aaa7027 JH |
125 | the `Makefile` to two revisions back, deletes hello.c by |
126 | mistake, 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 |
139 | If you have an unfortunate branch that is named `hello.c`, this |
140 | step would be confused as an instruction to switch to that branch. | |
141 | You 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 | 148 | branch would be done using: |
1be0659e JH |
149 | + |
150 | ------------ | |
151 | $ git checkout mytopic | |
152 | ------------ | |
153 | + | |
154 | However, your "wrong" branch and correct "mytopic" branch may | |
155 | differ in files that you have locally modified, in which case, | |
156 | the above checkout would fail like this: | |
157 | + | |
158 | ------------ | |
159 | $ git checkout mytopic | |
160 | fatal: Entry 'frotz' not uptodate. Cannot merge. | |
161 | ------------ | |
162 | + | |
163 | You can give the `-m` flag to the command, which would try a | |
164 | three-way merge: | |
165 | + | |
166 | ------------ | |
167 | $ git checkout -m mytopic | |
168 | Auto-merging frotz | |
169 | ------------ | |
170 | + | |
171 | After this three-way merge, the local modifications are _not_ | |
172 | registered in your index file, so `git diff` would show you what | |
173 | changes you made since the tip of the new branch. | |
174 | ||
175 | . When a merge conflict happens during switching branches with | |
176 | the `-m` option, you would see something like this: | |
177 | + | |
178 | ------------ | |
179 | $ git checkout -m mytopic | |
180 | Auto-merging frotz | |
181 | merge: warning: conflicts during merge | |
182 | ERROR: Merge conflict in frotz | |
183 | fatal: merge program failed | |
184 | ------------ | |
185 | + | |
186 | At this point, `git diff` shows the changes cleanly merged as in | |
187 | the previous example, as well as the changes in the conflicted | |
188 | files. 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 |
197 | Author |
198 | ------ | |
199 | Written by Linus Torvalds <torvalds@osdl.org> | |
200 | ||
201 | Documentation | |
202 | -------------- | |
203 | Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. | |
204 | ||
205 | GIT | |
206 | --- | |
a7154e91 | 207 | Part of the gitlink:git[7] suite |
7fc9d69f | 208 |