[PATCH v2] Docs: git checkout --orphan: `root commit' and `branch head'

[Michael Witten <mfwitten@gmail.com>]

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>
  http://article.gmane.org/gmane.comp.version-control.git/182170

and:

  git help glossary

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

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index c0a96e6..68ae6c9 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -125,29 +125,22 @@ 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.
+	Tell git to make the next commit you create 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 the branch head <new_branch> rather
+	than "master".
 +
-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.
+Furthermore, the index and the working tree are adjusted as if you ran
+"git checkout <start_point>"; by just running "git commit -a", you can
+create a root commit that records a tree similar to that of <start_point>.
 +
-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.
+Naturally, before creating the commit, you may manipulate the index in any
+way you want. For example, if you want to create a root commit that records
+a tree that is totally different from the one of <start_point>, then just
+clear the working tree and index by running "git rm -rf ." from the top
+level of the working tree, after which you may prepare your new working
+tree and index as desired.
 
 -m::
 --merge::
-- 
1.7.6.409.ge7a85