Sync with 1.7.2.3

[git.git] / Documentation / git-checkout.txt

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 37c1810e3fc8424868333a22094107e99764fc37..66e570113a077d2c52c4fc3ac09d24a272df5301 100644 (file)
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -9,39 +9,58 @@ SYNOPSIS
 --------
 [verse]
 'git checkout' [-q] [-f] [-m] [<branch>]
 --------
 [verse]
 'git checkout' [-q] [-f] [-m] [<branch>]

-'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<start_point>]
+'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]

 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
 'git checkout' --patch [<tree-ish>] [--] [<paths>...]
 
 DESCRIPTION
 -----------
 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
 'git checkout' --patch [<tree-ish>] [--] [<paths>...]
 
 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.
 
 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|-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.
++
+If `-B` is given, <new_branch> is created if it doesn't exist; otherwise, it
+is reset. This is the transactional equivalent of
++
+------------
+$ git branch -f <branch> [<start point>]
+$ git checkout <branch>
+------------
++
+that is to say, the branch is not reset/created unless "git checkout" is
+successful.
+
+'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.
 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
 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
 -------
 
 OPTIONS
 -------


@@ -67,6 +86,12 @@ entries; instead, unmerged entries are ignored.
        Create a new branch named <new_branch> and start it at
        <start_point>; see linkgit:git-branch[1] for details.
 
        Create a new branch named <new_branch> and start it at
        <start_point>; see linkgit:git-branch[1] for details.
 

+-B::
+       Creates the branch <new_branch> and start it at <start_point>;
+       if it already exists, then reset it to <start_point>. This is
+       equivalent to running "git branch" with "-f"; see
+       linkgit:git-branch[1] for details.
+

 -t::
 --track::
        When creating a new branch, set up "upstream" configuration. See
 -t::
 --track::
        When creating a new branch, set up "upstream" configuration. See


@@ -90,6 +115,31 @@ explicitly give a name with '-b' in such a case.
        Create the new branch's reflog; see linkgit:git-branch[1] for
        details.
 
        Create the new branch's reflog; see linkgit:git-branch[1] for
        details.
 

+--orphan::
+       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.
++
+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 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::
        When switching branches,
 -m::
 --merge::
        When switching branches,


@@ -136,6 +186,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 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.
 
 <new_branch>::
        Name for the new branch.


@@ -226,7 +280,7 @@ the above checkout would fail like this:
 +
 ------------
 $ git checkout mytopic
 +
 ------------
 $ git checkout mytopic

-fatal: Entry 'frotz' not uptodate. Cannot merge.
+error: You have local changes to 'frotz'; not switching branches.

 ------------
 +
 You can give the `-m` flag to the command, which would try a
 ------------
 +
 You can give the `-m` flag to the command, which would try a