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

From: Michael Witten <mfwitten@gmail.com>
Date: Sep 27, 2011, 17:09 UTC
Message-ID: <CAMOZ1BuK1dNdW9gVSnXCwtUBYL7Ef-4-uNNyTMf-wwVCa+0tuw@mail.gmail.com>
In-Reply-To: <vpq8vpa2agq.fsf@bauges.imag.fr>

On Tue, Sep 27, 2011 at 16:53, Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> wrote:

Show 18 quoted lines

> Michael Witten <mfwitten@gmail.com> writes:
>
>> I think that the last paragraph provides enough context to understand
>> its usefulness.
>
> The last paragraph tells the user how to commit something different from
> what is already here, which is pretty much the opposite.
>
> IOW, I see two uses for --orphan:
>
> 1) Publish the same tree without its history
>
> 2) Start a different project, but for some reason you wanted it to leave
>   in the same repository and you didn't want a "git init".
>
> The next paragraph documents 2), but your removed paragraph was
> documenting 1). Reading the new version, it feels like the user is
> encourraged to modify the index, while it's just an option.

Those 2 uses are not really different; both are manifestations of creating a new root commit using some tree.

The way I see it, people would think:

   1. I've got to get rid of this proprietary stuff
      before I publish as open source.

   2. I'll need a new root commit for the open source
      stuff, too, otherwise it'll still be accessible.

  3a. Aha! I can create a root commit based on the
      proprietary stuff, but altered in any way that
      I need.

  3b. Aha! I've already got a cleaned commit, I can
      just use that as the basis for the root commit
      without further alteration.

In any case, removing history is probably better handled by filter-branch or rebase, as I bet more often than not there are existing descendants of the proposed root commit that need to be played back anyway.