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

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

From: "Matthieu Moy" <Matthieu.Moy@grenoble-inp.fr>
> Michael Witten <mfwitten@gmail.com> writes:
>
>> -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.
>
> This part used to be just this in v1:
>
> -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
> +This can be useful when you want to publish a tree without exposing its
> +full history; for instance, 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.
>
> is it intentionnal that you discarded completely the paragraph? If so,
> then I disagree, the paragraph was one of the main motivation for
> someone to use --orphan, without it, someone may understand _what_ it
> does, but not _why_ it is useful.
>
> -- 

I agree - it would be wrong to discard the explanation of why it is used. As 
a relatively new git user, the man pages do need to properly inform the 
usage.

I have some orphan [i.e. independant] branches that are for documentation 
and for old matlab code that are both part of the project, but are separate 
from the various code branches. The original term `--orphan` was meaningful, 
though I do agree about it being a root commit.

It can be very easy for those that already know to presume knowledge of the 
reader that the reader doesn't have, leaving both sides frustrated. Reading 
the full manual could be a life times work to get all the nuances.