checkout: merge local modifications while switching branches.
[git/git.git] / Documentation / git-checkout.txt
CommitLineData
215a7ad1
JH
1git-checkout(1)
2===============
7fc9d69f
JH
3
4NAME
5----
215a7ad1 6git-checkout - Checkout and switch to a branch.
7fc9d69f
JH
7
8SYNOPSIS
9--------
1be0659e 10'git-checkout' [-f] [-b <new_branch>] [-m] [<branch>] [<paths>...]
7fc9d69f
JH
11
12DESCRIPTION
13-----------
4aaa7027
JH
14
15When <paths> are not given, this command switches branches, by
16updating the index and working tree to reflect the specified
17branch, <branch>, and updating HEAD to be <branch> or, if
18specified, <new_branch>.
19
20When <paths> are given, this command does *not* switch
21branches. It updates the named paths in the working tree from
22the index file (i.e. it runs `git-checkout-index -f -u`). In
23this case, `-f` and `-b` options are meaningless and giving
24either of them results in an error. <branch> argument can be
25used to specify a specific tree-ish to update the index for the
26given paths before updating the working tree.
27
7fc9d69f
JH
28
29OPTIONS
30-------
0270f7c5
LAS
31-f::
32 Force an re-read of everything.
33
34-b::
35 Create a new branch and start it at <branch>.
7fc9d69f 36
1be0659e
JH
37-m::
38 If you have local modifications to a file that is
39 different between the current branch and the branch you
40 are switching to, the command refuses to switch
41 branches, to preserve your modifications in context.
42 With this option, a three-way merge between the current
43 branch, your working tree contents, and the new branch
44 is done, and you will be on the new branch.
45+
46When a merge conflict happens, the index entries for conflicting
47paths are left unmerged, and you need to resolve the conflicts
48and mark the resolved paths with `git update-index`.
49
0270f7c5
LAS
50<new_branch>::
51 Name for the new branch.
7fc9d69f 52
0270f7c5
LAS
53<branch>::
54 Branch to checkout; may be any object ID that resolves to a
55 commit. Defaults to HEAD.
7fc9d69f 56
4aaa7027 57
1be0659e
JH
58EXAMPLES
59--------
4aaa7027 60
1be0659e 61. The following sequence checks out the `master` branch, reverts
4aaa7027
JH
62the `Makefile` to two revisions back, deletes hello.c by
63mistake, and gets it back from the index.
1be0659e 64+
4aaa7027 65------------
1e2ccd3a
JH
66$ git checkout master <1>
67$ git checkout master~2 Makefile <2>
4aaa7027 68$ rm -f hello.c
1e2ccd3a
JH
69$ git checkout hello.c <3>
70
71<1> switch branch
72<2> take out a file out of other commit
73<3> or "git checkout -- hello.c", as in the next example.
4aaa7027 74------------
1be0659e 75+
4aaa7027
JH
76If you have an unfortunate branch that is named `hello.c`, the
77last step above would be confused as an instruction to switch to
78that branch. You should instead write:
1be0659e 79+
4aaa7027
JH
80------------
81$ git checkout -- hello.c
82------------
83
1be0659e
JH
84. After working in a wrong branch, switching to the correct
85branch you would want to is done with:
86+
87------------
88$ git checkout mytopic
89------------
90+
91However, your "wrong" branch and correct "mytopic" branch may
92differ in files that you have locally modified, in which case,
93the above checkout would fail like this:
94+
95------------
96$ git checkout mytopic
97fatal: Entry 'frotz' not uptodate. Cannot merge.
98------------
99+
100You can give the `-m` flag to the command, which would try a
101three-way merge:
102+
103------------
104$ git checkout -m mytopic
105Auto-merging frotz
106------------
107+
108After this three-way merge, the local modifications are _not_
109registered in your index file, so `git diff` would show you what
110changes you made since the tip of the new branch.
111
112. When a merge conflict happens during switching branches with
113the `-m` option, you would see something like this:
114+
115------------
116$ git checkout -m mytopic
117Auto-merging frotz
118merge: warning: conflicts during merge
119ERROR: Merge conflict in frotz
120fatal: merge program failed
121------------
122+
123At this point, `git diff` shows the changes cleanly merged as in
124the previous example, as well as the changes in the conflicted
125files. Edit and resolve the conflict and mark it resolved with
126`git update-index` as usual:
127+
128------------
129$ edit frotz
130$ git update-index frotz
131------------
132
4aaa7027 133
7fc9d69f
JH
134Author
135------
136Written by Linus Torvalds <torvalds@osdl.org>
137
138Documentation
139--------------
140Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
141
142GIT
143---
a7154e91 144Part of the gitlink:git[7] suite
7fc9d69f 145