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

[Michael J Gruber <git@drmicha.warpmail.net>]

Michael Witten venit, vidit, dixit 27.09.2011 16:43:
> 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 |   13 +++++--------
>  1 files changed, 5 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index c0a96e6..c963a0f 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -125,19 +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.
> +	Tell git to make the next commit you make a root commit referenced by
> +	the branch head <new_branch>.

I recall objecting to the name "--orphan" (to no avail) because the
first commit is the root commit and there is no "orphan branch nor
"parent branch"...

In any case, I think the above is indeed an improvement, but I would
keep at least something which connects to the misnamed option, e.g.

...root commit (i.e. without parents) referenced by...

>  +
>  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
> +that records a set of paths similar to <start_point> by just running
>  "git commit -a" to make the root commit.

"similar" is an understatement here, maybe "as in"?

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

+1 ;)

Michael