Re: [PATCH v3] git checkout: create unparented branch by --orphan

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

Chris Johnsen <chris_johnsen@pobox.com> writes:

> --orphan::
> 	Create a new, 'orphan' branch named <new_branch>, and start it
> 	at <start_point>. The first commit made on this new branch will
> 	have no parents (it will be the root of a new history that is
> 	not connected to any the other branches or commits).
> +
> An orphan branch allows you to start a new history that records a set of
> paths similar to <start_point>.

Strictly speaking, an orphan branch allows you to start a new history that
does not have any existing commit as its ancestry, and that is all there
to it.  While the "mostly common paths" aspect is worth mentioning, as it
is the use case it primarily targets, it is still secondary to the
description of "what it does."  "What it is used for" should come after
the reader is told "what it does."

It would probably be better to say that the index and the working tree is
kept intact during --orphan process as part of "what it does", before
talking about "mostly common paths":

	Create a new branch <new_branch> and switch to it.  The first
	commit you will make on this branch will become the root of a new
	history, disconnected from any of existing commits.  

	The index and the working tree is adjusted as if you ran "git
	checkout <start_point>" (without -b nor paths), to allow you to
	easily record the root commit of the new history that records a
	set of paths similar to <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.

Good.

> +
> If you want to start a disconnected history that records a set of paths
> that is totally different from <start_point>, you may want to clear the
> index and the working tree after creating the orphan branch.
> Run `git rm -rf .` from the top level of the working tree, then prepare
> your new files by copying them from elsewhere, extracting a tarball, or
> otherwise populating the working tree.

Good, even though I am tempted to suggest rephrasing it further:

        If you want to start a disconnected history that records a set of
        paths that is totally different from <start_point>, you could
        clear the index and the working tree after creating the orphan
        branch by running `git rm -rf .` from the top level of the working
        tree.  Then prepare your new files by copying them from elsewhere,
        extracting a tarball, or otherwise populating the working tree.
	In general, however, it is cleaner and easier to create such an
        unrelated history in a separate repository than creating in the
        same repository.