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

[Michael Witten <mfwitten@gmail.com>]

On Thu, Sep 29, 2011 at 18:59, Junio C Hamano <gitster@pobox.com> wrote:
> 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::
>

Fsck-you-by: Michael Witten <mfwitten@gmail.com>