Documentation/checkout: clarify description
git checkout can be used to switch branches and to retrieve files from the index or an arbitrary tree. Split the description into subsections corresponding to each mode to make each use easier to understand. Helped-by: Jeff King <peff@peff.net> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jonathan Nieder committed
Jun 1, 2010 at 02:25 UTC
b831deda174da7864ca5d529f53296af3f41ee18
1 file changed
+21
-19
Documentation/git-checkout.txt
+21
-19
@@ -15,39 +15,41 @@ SYNOPSIS
15
16
DESCRIPTION
17
-----------
18
-Retrieves files from the index or specified tree and writes them
19
-to the working tree.
18
+Updates files in the working tree to match the version in the index
19
+or the specified tree. If no paths are given, 'git checkout' will
20
+also update `HEAD` to set the specified branch as the current
21
+branch.
22
21
-'git checkout' [-b <new branch>] [<branch>]::
23
+'git checkout' [<branch>]::
24
+'git checkout' -b <new branch> [<start point>]::
25
23
- When <paths> are not given, this command switches branches by
24
- updating the index, working tree, and HEAD to reflect the
25
- specified branch.
26
+ This form switches branches by updating the index, working
27
+ tree, and HEAD to reflect the specified branch.
28
+
27
-If `-b` is given, a new branch is created and checked out, as if
28
-linkgit:git-branch[1] were called; in this case you can
29
-use the --track or --no-track options, which will be passed to `git
30
-branch`. As a convenience, --track without `-b` implies branch
31
-creation; see the description of --track below.
29
+If `-b` is given, a new branch is created as if linkgit:git-branch[1]
30
+were called and then checked out; in this case you can
31
+use the `--track` or `--no-track` options, which will be passed to
32
+'git branch'. As a convenience, `--track` without `-b` implies branch
33
+creation; see the description of `--track` below.
34
33
-'git checkout' [--patch] [<tree-ish>] [--] [<pathspec>...]::
35
+'git checkout' [--patch] [<tree-ish>] [--] <pathspec>...::
36
35
- When <paths> or --patch are given, this command does *not* switch
37
+ When <paths> or `--patch` are given, 'git checkout' *not* switch
38
branches. It updates the named paths in the working tree from
37
- the index file, or from a named <tree-ish> (most often a commit). In
39
+ the index file or from a named <tree-ish> (most often a commit). In
40
this case, the `-b` and `--track` options are meaningless and giving
41
either of them results in an error. The <tree-ish> argument can be
42
used to specify a specific tree-ish (i.e. commit, tag or tree)
43
to update the index for the given paths before updating the
44
working tree.
45
+
44
-The index may contain unmerged entries after a failed merge. By
45
-default, if you try to check out such an entry from the index, the
46
+The index may contain unmerged entries because of a previous failed merge.
47
+By default, if you try to check out such an entry from the index, the
48
checkout operation will fail and nothing will be checked out.
47
-Using -f will ignore these unmerged entries. The contents from a
49
+Using `-f` will ignore these unmerged entries. The contents from a
50
specific side of the merge can be checked out of the index by
49
-using --ours or --theirs. With -m, changes made to the working tree
50
-file can be discarded to recreate the original conflicted merge result.
51
+using `--ours` or `--theirs`. With `-m`, changes made to the working tree
52
+file can be discarded to re-create the original conflicted merge result.
53
54
OPTIONS
55
-------