Merge branch 'jl/clone-recurse-sm-synonym'

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

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 1bacd2e1044f5b3b7d5a60e1687387cc277fc52a..880763d391d18364485edc2e1e3dfc6f52243973 100644 (file)
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -9,7 +9,7 @@ SYNOPSIS
 --------
 [verse]
 'git checkout' [-q] [-f] [-m] [<branch>]
-'git checkout' [-q] [-f] [-m] [[-b|--orphan] <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>...]
 
@@ -21,7 +21,7 @@ also update `HEAD` to set the specified branch as the current
 branch.
 
 'git checkout' [<branch>]::
-'git checkout' -b <new branch> [<start point>]::
+'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.
@@ -31,17 +31,28 @@ 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.
+       When <paths> or `--patch` are given, 'git checkout' 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 because of a previous failed merge.
 By default, if you try to check out such an entry from the index, the
@@ -75,13 +86,19 @@ 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.
 
+-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
        "--track" in linkgit:git-branch[1] for details.
 +
 If no '-b' option is given, the name of the new branch will be
-derived from the remote branch.  If "remotes/" or "refs/remotes/"
+derived from the remote-tracking branch.  If "remotes/" or "refs/remotes/"
 is prefixed it is stripped away, and then the part up to the
 next slash (which would be the nickname of the remote) is removed.
 This would tell us to use "hack" as the local branch when branching
@@ -170,7 +187,7 @@ 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
+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`.