[PATCH v4] Docs: git checkout --orphan: Copyedit, and s/root commit/orphan branch/

[Michael Witten <mfwitten@gmail.com>]

It's copyediting; it's best just to read the damn patch, particularly when
there are no subtle details to be considered beyond the exhausting game of
making everybody involved in the email thread feel like he or she has gotten
a portion of the bikeshed painted a certain color.

See:

  Re: Can a git changeset be created with no parent
  Carlos Martín Nieto <cmn@elego.de>
  Message-ID: <1317073309.5579.9.camel@centaur.lab.cmartin.tk>

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/git-checkout.txt |   69 ++++++++++++++++++++++++++++-----------
 1 files changed, 49 insertions(+), 20 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index c0a96e6..bf042c2 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -125,29 +125,58 @@ explicitly give a name with '-b' in such a case.
 	below 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.
+--orphan::
+	Perform these two tasks:
++
+--
+	* Adjust the working tree and index as if you ran
+	  "git checkout <start_point>".
+
+	* Set up git to turn the next commit you create into a root commit
+	  (that is, a commit without any parent); creating the next commit
+	  is similar to creating the first commit after running "git init",
+	  except that the new commit will be referenced by <new_branch>
+	  rather than "master".
+--
++
+Then, by just running "git commit", you can create a root commit
+with a tree that is exactly the same as the tree of <start_point>.
+Alternatively, before creating the commit, you may manipulate the
+index in any way you want; for example, to create a root commit with
+a tree that is totally different from the tree of <start_point>,
+just clear the working tree and index first: From the top level of
+the working tree, run "git rm -rf .", and then prepare your new
+working tree and index as desired.
++
+There are two common uses for this option:
++
+--
+	Separate history::
+		Suppose that for convenience, you want to maintain
+		in the same repository as your project some ancillary
+		material that is infrequently altered.  In such a case,
+		it may not make much sense to interleave the history of
+		that material with the history of your project; you can
+		use the "--orphan" option in order to create completely
+		separate histories.
+
+	Hidden history::
+		Suppose you have a project that has proprietary
+		material that is never meant to be released to the
+		public, yet you now want to maintain an open source
+		history that may be published widely.
++
+In this case, it would not be enough just to remove the proprietary
+material from the working tree and then create a new commit, because
+the proprietary material would still be accessible through the new
+commit's ancestry; the proprietary history must be hidden from the new
+commit, and the "--orphan" option allows you to do so by ensuring that
+the new commit has no parent.
++
+However, when there are multiple commits that are already suitable for
+the open source history (or that you want to make suitable), you should
+instead consider working with linkgit:git-filter-branch[1] and possibly
+linkgit:git-rebase[1].
+--
 
 -m::
 --merge::
-- 
1.7.6.409.ge7a85