Merge branch 'em/checkout-orphan'

* em/checkout-orphan:
log_ref_setup: don't return stack-allocated array
bash completion: add --orphan to 'git checkout'
t3200: test -l with core.logAllRefUpdates options
checkout --orphan: respect -l option always
refs: split log_ref_write logic into log_ref_setup
Documentation: alter checkout --orphan description

diff --combined Documentation/git-checkout.txt
index afda5c36b5ac0061d94d706cd7a07ef8197b6b31,b84ec26276ed47f4b7d002f6e942cea28127ed34..1548312b3581450dab5e446935afba97616124b1
--- 1/Documentation/git-checkout.txt
--- 2/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@@ -91,22 -91,29 +91,29 @@@ explicitly give a name with '-b' in suc
        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.
  +
- 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.
+ 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.
  +
- 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.
+ 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::
@@@ -154,10 -161,6 +161,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.

diff --combined contrib/completion/git-completion.bash
index 57245a8c01fa3aba4f9e3f2bc258b40f38f446c0,b70cca13fd2d926cc1c5c5374c0d65413e34b409..aebb0b689040c3f1c1023e3ddf07779178a6bdfb
--- 1/contrib/completion/git-completion.bash
--- 2/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@@ -797,7 -797,6 +797,7 @@@ _git_branch (
                __gitcomp "
                        --color --no-color --verbose --abbrev= --no-abbrev
                        --track --no-track --contains --merged --no-merged
 +                      --set-upstream
                        "
                ;;
        *)
@@@ -842,7 -841,7 +842,7 @@@ _git_checkout (
        --*)
                __gitcomp "
                        --quiet --ours --theirs --track --no-track --merge
-                       --conflict= --patch
+                       --conflict= --orphan --patch
                        "
                ;;
        *)