Merge branch 'tc/checkout-B'

* tc/checkout-B:
builtin/checkout: handle -B from detached HEAD correctly
builtin/checkout: learn -B
builtin/checkout: reword hint for -b
add tests for checkout -b

diff --combined Documentation/git-checkout.txt
index 1bacd2e1044f5b3b7d5a60e1687387cc277fc52a,97c51449f76af11f4eab55dc466aacbe79211134..66e570113a077d2c52c4fc3ac09d24a272df5301
--- 1/Documentation/git-checkout.txt
--- 2/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@@ -9,7 -9,7 +9,7 @@@ SYNOPSI
  --------
  [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 +21,7 @@@ also update `HEAD` to set the specifie
  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,6 -31,17 +31,17 @@@ were called and then checked out; in th
  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>...::
  
@@@ -75,6 -86,12 +86,12 @@@ entries; instead, unmerged entries are 
        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
@@@ -263,7 -280,7 +280,7 @@@ the above checkout would fail like this
  +
  ------------
  $ 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