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

[Michael Witten <mfwitten@gmail.com>]

On Tue, Sep 27, 2011 at 15:49, Michael J Gruber
<git@drmicha.warpmail.net> wrote:

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

It seems like a more logical approach would be instead for "git
commit" to take a "--root" option that would create a new root commit
based on the current index and then point the current branch head to
the new root commit. Thus:

  $ git checkout -b new_branch old_branch
  $ # Manipulate or not
  $ git commit --root

That's how people think.

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

Agreed! See the new v2 patch:

  http://article.gmane.org/gmane.comp.version-control.git/182245

>>  +
>>  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"?

Damn! I'll send a patch on top of v2.

>>  +
>> -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 ;)

Actually, in v2, I got rid of that entire paragraph, as it's redundant
and difficult to state succinctly AND consistently.