aboutsummaryrefslogtreecommitdiff
path: root/Documentation/git-checkout.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/git-checkout.txt')
-rw-r--r--Documentation/git-checkout.txt93
1 files changed, 56 insertions, 37 deletions
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 4505eb6d8..261dd90c3 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -15,33 +15,41 @@ SYNOPSIS
DESCRIPTION
-----------
-
-When <paths> are not given, this command switches branches by
-updating the index, working tree, and HEAD to reflect the specified
+Updates files in the working tree to match the version in the index
+or the specified tree. If no paths are given, 'git checkout' will
+also update `HEAD` to set the specified branch as the current
branch.
-If `-b` is given, a new branch is created and checked out, as if
-linkgit:git-branch[1] were called; in this case you can
-use the --track or --no-track options, which will be passed to `git
-branch`. As a convenience, --track without `-b` implies branch
-creation; see the description of --track below.
-
-When <paths> or --patch are given, this command does *not* switch
-branches. It updates the named paths in the working tree from
-the index file, or from a named <tree-ish> (most often a commit). In
-this case, the `-b` and `--track` options are meaningless and giving
-either of them results in an error. The <tree-ish> argument can be
-used to specify a specific tree-ish (i.e. commit, tag or tree)
-to update the index for the given paths before updating the
-working tree.
-
-The index may contain unmerged entries after a failed merge. By
-default, if you try to check out such an entry from the index, the
+'git checkout' [<branch>]::
+'git checkout' -b <new branch> [<start point>]::
+
+ This form switches branches by updating the index, working
+ tree, and HEAD to reflect the specified branch.
++
+If `-b` is given, a new branch is created as if linkgit:git-branch[1]
+were called and then checked out; in this case you can
+use the `--track` or `--no-track` options, which will be passed to
+'git branch'. As a convenience, `--track` without `-b` implies branch
+creation; see the description of `--track` below.
+
+'git checkout' [--patch] [<tree-ish>] [--] <pathspec>...::
+
+ When <paths> or `--patch` are given, 'git checkout' *not* switch
+ branches. It updates the named paths in the working tree from
+ the index file or from a named <tree-ish> (most often a commit). In
+ this case, the `-b` and `--track` options are meaningless and giving
+ either of them results in an error. The <tree-ish> argument can be
+ used to specify a specific tree-ish (i.e. commit, tag or tree)
+ to update the index for the given paths before updating the
+ working tree.
++
+The index may contain unmerged entries because of a previous failed merge.
+By default, if you try to check out such an entry from the index, the
checkout operation will fail and nothing will be checked out.
-Using -f will ignore these unmerged entries. The contents from a
+Using `-f` will ignore these unmerged entries. The contents from a
specific side of the merge can be checked out of the index by
-using --ours or --theirs. With -m, changes made to the working tree
-file can be discarded to recreate the original conflicted merge result.
+using `--ours` or `--theirs`. With `-m`, changes made to the working tree
+file can be discarded to re-create the original conflicted merge result.
OPTIONS
-------
@@ -91,22 +99,29 @@ explicitly give a name with '-b' in such a case.
details.
--orphan::
- Create a new branch named <new_branch>, unparented to any other
- branch. The new branch you switch to does not have any commit
- and after the first one it will become the root of a new history
- completely unconnected from all the other branches.
+ Create a new 'orphan' branch, named <new_branch>, started from
+ <start_point> and switch to it. The first commit made on this
+ new branch will have no parents and it will be the root of a new
+ history totally disconnected from all the other branches and
+ commits.
++
+The index and the working tree are adjusted as if you had previously run
+"git checkout <start_point>". This allows you to start a new history
+that records a set of paths similar to <start_point> by easily running
+"git commit -a" to make the root commit.
+
-When you use "--orphan", the index and the working tree are kept intact.
-This allows you to start a new history that records set of paths similar
-to that of the start-point commit, which is useful when you want to keep
-different branches for different audiences you are working to like when
-you have an open source and commercial versions of a software, for example.
+This can be useful when you want to publish the tree from a commit
+without exposing its full history. You might want to do this to publish
+an open source branch of a project whose current tree is "clean", but
+whose full history contains proprietary or otherwise encumbered bits of
+code.
+
-If you want to start a disconnected history that records set of paths
-totally different from the original branch, you may want to first clear
-the index and the working tree, by running "git rm -rf ." from the
-top-level of the working tree, before preparing your files (by copying
-from elsewhere, extracting a tarball, etc.) in the working tree.
+If you want to start a disconnected history that records a set of paths
+that is totally different from the one of <start_point>, then you should
+clear the index and the working tree right after creating the orphan
+branch by running "git rm -rf ." from the top level of the working tree.
+Afterwards you will be ready to prepare your new files, repopulating the
+working tree, by copying them from elsewhere, extracting a tarball, etc.
-m::
--merge::
@@ -154,6 +169,10 @@ edits from your current working tree.
As a special case, the `"@\{-N\}"` syntax for the N-th last branch
checks out the branch (instead of detaching). You may also specify
`-` which is synonymous with `"@\{-1\}"`.
++
+As a further special case, you may use `"A...B"` as a shortcut for the
+merge base of `A` and `B` if there is exactly one merge base. You can
+leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
<new_branch>::
Name for the new branch.