[PATCH] Documentation/git-checkout.txt: Explain --orphan without introducing an undefined "orphan branch"

[Junio C Hamano <gitster@pobox.com>]

The name of the `--orphan` option to `checkout` is meant to express that
the next commit made on the branch does not have any parent (specifically,
it will not be a child of the current nor start_point commit), but the
glossary calls such a commit 'a root commit'. The explanation however used
an undefined term 'orphan branch', adding mental burden to the first time
readers.

Reword the description to clarify what it does without introducing a new
term, stressing that it is similar to what happens to the "master' branch
in a brand new repository created by `git init`. Also explain that it is
OK to tweak the index and the working tree before creating a commit.

Also mildly discourage the users from using this to originate a new root
commit that tracks material that is unrelated to the main branches in a
single repository with a working tree, and hint a better way of starting
an unrelated history, as it seems to be a common abuse of this option.

We may want to give a synonym `--new-root` to this option and eventually
deprecate the `--orphan` option, as "parent vs orphan" might not
immediately "click" to non native speakers of English (like myself), but
that is a separate topic.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---

 * I am inclined to suggest doing something like this instead.

 Documentation/git-checkout.txt |   26 ++++++++++++++------------
 1 files changed, 14 insertions(+), 12 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index c0a96e6..63d164e 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -125,16 +125,16 @@ 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.
+	Adjust the working tree and the index as if you checked out the
+	<start_point>. The next commit begins a history that is not connected
+	to any other branches, as if you ran `git init` in a new repository,
+	except that the commit will be made on the <new_branch> branch, not on
+	the "master" branch.
 +
-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.
+Running "git commit" immediately after doing this will record a root commit
+with a tree that is the same as the tree of the <start_point>. You may
+manipulate the index before creating the commit to record a tree that is
+different from that of the <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
@@ -143,11 +143,13 @@ 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.
+that is totally different from the one of <start_point>, you could
+clear the index and the working tree right after "git checkout --orphan"
+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.
+However, such a use case to keep track of a history that is unrelated to
+the main project is better done by starting a new, separate repository.
 
 -m::
 --merge::