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

1 files changed, 21 insertions, 14 deletions

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index afda5c36b5..1548312b35 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -91,22 +91,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.
 +
-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::