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