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

["Philip Oakley" <philipoakley@iee.org>]

From: "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::

Can I suggest    "Distinct History::"    as this title.
'separate' is both a verb and a noun, and it is easy to misread the title as 
if it is the verb, which would then be describing the action of creating the 
hidden history (the second title), with resulting misunderstanding. 
"Distinct" avoids the problem. The use of 'seperate' at the end is in 
context,  so not an issue.

> + 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
>