Can a git changeset be created with no parent

Can a git changeset be created with no parent

[vra5107]

Hi

        I am currently in the process of converting a large hg repository.
One of the changesets has no parents assigned. So to mirror that is it
possible to create a git changeset that doesnot have a parent ?

Thanks
Venkat

--
View this message in context: http://git.661346.n2.nabble.com/Can-a-git-changeset-be-created-with-no-parent-tp6829212p6829212.html
Sent from the git mailing list archive at Nabble.com.

Re: Can a git changeset be created with no parent

[Andreas Ericsson]

On 09/25/2011 04:15 PM, vra5107 wrote:
> Hi
> 
>          I am currently in the process of converting a large hg repository.
> One of the changesets has no parents assigned. So to mirror that is it
> possible to create a git changeset that doesnot have a parent ?
> 

Yes. Each and every project git has ever managed starts with a commit
just like that. In git lingo, it's called a "root commit".

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Considering the successes of the wars on alcohol, poverty, drugs and
terror, I think we should give some serious thought to declaring war
on peace.

Re: Can a git changeset be created with no parent

[Carlos Martín Nieto]

[-- Attachment #1: Type: text/plain, Size: 667 bytes --]

On Sun, 2011-09-25 at 07:15 -0700, vra5107 wrote:
> Hi
> 
>         I am currently in the process of converting a large hg repository.
> One of the changesets has no parents assigned. So to mirror that is it
> possible to create a git changeset that doesnot have a parent ?

They're called commits in git, and yes it's possible. They are called
orphan commits and it's what you get when you do the first commit in the
repository.

You can do this with 'git checkout --orphan somebranch'. Notice that the
index will be kept, you'll need to either use 'git rm' or 'git add -A'.

There is a longer explanation in the manpage for 'git checkout'.

   cmn

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 490 bytes --]

Re: Can a git changeset be created with no parent

[Junio C Hamano]

Carlos Martín Nieto <cmn@elego.de> writes:

> On Sun, 2011-09-25 at 07:15 -0700, vra5107 wrote:
>> Hi
>> 
>>         I am currently in the process of converting a large hg repository.
>> One of the changesets has no parents assigned. So to mirror that is it
>> possible to create a git changeset that doesnot have a parent ?
>
> They're called commits in git, and yes it's possible. They are called
> orphan commits and it's what you get when you do the first commit in the

Just to set the terminology straight, s/orphan/root/;

> repository.
>
> You can do this with 'git checkout --orphan somebranch'. Notice that the

The orphan here refers to the fact that the next commit will not be a
child of the current commit. The resulting one is a "root" commit.

Re: Can a git changeset be created with no parent

[Carlos Martín Nieto]

[-- Attachment #1: Type: text/plain, Size: 1007 bytes --]

On Mon, 2011-09-26 at 12:25 -0700, Junio C Hamano wrote:
> Carlos Martín Nieto <cmn@elego.de> writes:
> 
> > On Sun, 2011-09-25 at 07:15 -0700, vra5107 wrote:
> >> Hi
> >> 
> >>         I am currently in the process of converting a large hg repository.
> >> One of the changesets has no parents assigned. So to mirror that is it
> >> possible to create a git changeset that doesnot have a parent ?
> >
> > They're called commits in git, and yes it's possible. They are called
> > orphan commits and it's what you get when you do the first commit in the
> 
> Just to set the terminology straight, s/orphan/root/;

Ah, quite.

> 
> > repository.
> >
> > You can do this with 'git checkout --orphan somebranch'. Notice that the
> 
> The orphan here refers to the fact that the next commit will not be a
> child of the current commit. The resulting one is a "root" commit.

The manpage mentions that an orphan branch is created. I guess that's
where I got my "orphan commit" name.


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 490 bytes --]

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

[Michael Witten]

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

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

[Matthieu Moy]

Michael Witten <mfwitten@gmail.com> writes:

> +	Tell git to make the next commit you make a root commit

I'd even add 

  (just like the first commit after "git init")

at this point.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

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

[Michael Witten]

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 |   32 ++++++++++++++++----------------
 1 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index c0a96e6..68ae6c9 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -125,29 +125,22 @@ 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 create a root commit (that is,
+	a commit without any parent); creating the next commit is similar to
+	creating the first commit after running "git init", except that the
+	new commit will be referenced by the branch head <new_branch> rather
+	than "master".
 +
-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.
+Furthermore, the index and the working tree are adjusted as if you ran
+"git checkout <start_point>"; by just running "git commit -a", you can
+create a root commit that records a tree similar to that of <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.
-+
-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.
-Afterwards you will be ready to prepare your new files, repopulating the
-working tree, by copying them from elsewhere, extracting a tarball, etc.
+Naturally, before creating the commit, you may manipulate the index in any
+way you want. For example, if you want to create a root commit that records
+a tree that is totally different from the one of <start_point>, then just
+clear the working tree and index by running "git rm -rf ." from the top
+level of the working tree, after which you may prepare your new working
+tree and index as desired.
 
 -m::
 --merge::
-- 
1.7.6.409.ge7a85

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

[Michael J Gruber]

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

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

[Matthieu Moy]

Michael Witten <mfwitten@gmail.com> writes:

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

This part used to be just this in v1:

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

is it intentionnal that you discarded completely the paragraph? If so,
then I disagree, the paragraph was one of the main motivation for
someone to use --orphan, without it, someone may understand _what_ it
does, but not _why_ it is useful.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

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

[Michael Witten]

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.

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

[Michael Witten]

On Tue, Sep 27, 2011 at 16:01, Matthieu Moy
<Matthieu.Moy@grenoble-inp.fr> wrote:
> Michael Witten <mfwitten@gmail.com> writes:
>
>> -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.
>
> This part used to be just this in v1:
>
> -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.
>
> is it intentionnal that you discarded completely the paragraph? If so,
> then I disagree, the paragraph was one of the main motivation for
> someone to use --orphan, without it, someone may understand _what_ it
> does, but not _why_ it is useful.

It was intentional; I was finding it difficult to express that
paragraph succintly in a way that is consistent with correct
terminology. Then I realized it's fairly redundant, anyway.

I think that the last paragraph provides enough context to understand
its usefulness. Also, anybody who ever independently decided to carve
out proprietary bits in that way would immediately recognize the need
for creating a commit without parents, a notion which would lead him
or her pretty quickly to this documentation or jog his or her memory
about it based on the text of v2.

If everyone else is quite set on keeping that paragraph, though, I'll
take the challenge; however, I think that would be a waste of time.

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

[Matthieu Moy]

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.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

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

[Michael Witten]

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

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

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

[Junio C Hamano]

Michael Witten <mfwitten@gmail.com> writes:

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

This may indeed be an improvement. I suspect that we'd need to think about
it a bit more, but it feels right (perhaps introduce this new option,
deprecate --orphan from the checkout, and then eventually remove it
sometime in 1.8.0 timeframe).

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

I do not think "as in" is an improvement. It completely ignores the
"Manipulate or not" part in the above, and "similar" was very much an
attempt to say "you do not have to commit it right away, but start from
the state and commit a deviation of it".

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

[Michael Witten]

On Tue, 27 Sep 2011 10:25:10 -0700, Junio C Hamano wrote:

> Michael Witten <mfwitten@gmail.com> writes:
>
>> 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.
>
> This may indeed be an improvement. I suspect that we'd need to think about
> it a bit more, but it feels right (perhaps introduce this new option,
> deprecate --orphan from the checkout, and then eventually remove it
> sometime in 1.8.0 timeframe).
>
>>>>  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"?
>
> I do not think "as in" is an improvement. It completely ignores the
> "Manipulate or not" part in the above, and "similar" was very much an
> attempt to say "you do not have to commit it right away, but start from
> the state and commit a deviation of it".

Actually, that kind of change might make a lot of sense with respect to
[PATCH v2]; here's the kind of text that [PATCH v2.1] will yield:

  ...
  
  Furthermore, the working tree and the index are adjusted as if
  you ran "git checkout <start_point>"; thus, by just running
  "git commit", you can create a root commit with a tree that is
  exactly the same as the tree of <start_point>.
  
  Naturally, before creating the commit, you may manipulate the
  index in any way you want. For example, if you want to create
  a root commit with a tree that is totally different from the
  tree of <start_point>, then just clear the working tree and
  index first: From the top level of the working tree, run
  "git rm -rf .", and then prepare your new working tree
  and index as desired.

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

[Eric Raible]

On 11:59 AM, Junio C Hamano wrote:
> Michael Witten <mfwitten@gmail.com> writes:
> 
>> 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.

Not this person.

I like the idea but I'd rather see:

	git commit --no-parent

"parent" at least appears in gitk and therefore newcomers will prob
have a better chance of understanding the intent w/out needing to
otherwise unnecessary terminology.

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

[Philip Oakley]

From: "Matthieu Moy" <Matthieu.Moy@grenoble-inp.fr>
> Michael Witten <mfwitten@gmail.com> writes:
>
>> -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.
>
> This part used to be just this in v1:
>
> -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.
>
> is it intentionnal that you discarded completely the paragraph? If so,
> then I disagree, the paragraph was one of the main motivation for
> someone to use --orphan, without it, someone may understand _what_ it
> does, but not _why_ it is useful.
>
> -- 

I agree - it would be wrong to discard the explanation of why it is used. As 
a relatively new git user, the man pages do need to properly inform the 
usage.

I have some orphan [i.e. independant] branches that are for documentation 
and for old matlab code that are both part of the project, but are separate 
from the various code branches. The original term `--orphan` was meaningful, 
though I do agree about it being a root commit.

It can be very easy for those that already know to presume knowledge of the 
reader that the reader doesn't have, leaving both sides frustrated. Reading 
the full manual could be a life times work to get all the nuances.

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

[Philip Oakley]

From: "Eric Raible" <raible@nextest.com>
> On 11:59 AM, Junio C Hamano wrote:
>> Michael Witten <mfwitten@gmail.com> writes:
>>
>>> 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.
>
> Not this person.
>
> I like the idea but I'd rather see:
>
> git commit --no-parent
>
> "parent" at least appears in gitk and therefore newcomers will prob
> have a better chance of understanding the intent w/out needing to
> otherwise unnecessary terminology.
> --
I think this feels and sounds sensible.  And better located within the 
'commit' command, rather than 'checkout --orphan' which was more obscure 
(and difficult to find).
Philip 

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

[Jeff King]

On Tue, Sep 27, 2011 at 10:31:17PM +0100, Philip Oakley wrote:

> >Not this person.
> >
> >I like the idea but I'd rather see:
> >
> >git commit --no-parent
> >
> >"parent" at least appears in gitk and therefore newcomers will prob
> >have a better chance of understanding the intent w/out needing to
> >otherwise unnecessary terminology.
> >--
> I think this feels and sounds sensible.  And better located within
> the 'commit' command, rather than 'checkout --orphan' which was more
> obscure (and difficult to find).

Keep in mind that making it part of commit is potentially much more
dangerous. With "checkout --orphan", you are making a _new_ branch that
has no parents. Committing on it will make a disconnected history, but
your original branch is still there.

With "git commit --no-parent", you are disconnecting history on the
_current_ branch. Which means you are throwing away the old history
completely. I.e., it is about as dangerous as "git branch -d", which we
usually protect with a "force" flag[1].

So at the very least, the documentation for the new option would need to
make the consequences very clear, and that one should run it on a newly
created branch if they don't want to throw away the old history.

-Peff

[1] Actually, it's similarly dangerous to "git reset", which doesn't
    have a force flag. But then, "git reset" is frequently brought up as
    the most dangerous and confusing command by new git users.

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

[Michael Witten]

On Tue, Sep 27, 2011 at 21:42, Jeff King <peff@peff.net> wrote:

> Keep in mind that making it part of commit is potentially much more
> dangerous. With "checkout --orphan", you are making a _new_ branch that
> has no parents. Committing on it will make a disconnected history, but
> your original branch is still there.
>
> With "git commit --no-parent", you are disconnecting history on the
> _current_ branch. Which means you are throwing away the old history
> completely. I.e., it is about as dangerous as "git branch -d", which we
> usually protect with a "force" flag[1].

If I might be a bit more pedantic:

  With "checkout --orphan", you are setting up a new branch head
  to point to an as-yet-to-exist commit that will have no parents.
  Your original branch head is not changed.

  With "git commit --no-parent", you would be altering the current
  branch head, which means you are potentially leaving as a dangling
  commit the commit to which that branch head originally pointed.
  I.e., it is about as dangerous as "git reset --hard <new_root_commit>",
  something for which we do NOT provide any protection.

For instance, what if I want the current branch head to point to that
new root commit? The existing solution requires juggling branch names;
why can't git just do what I tell it to do (as with "git reset")?
After all, "git commit --no-parent" is pretty name explicit.

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

[Jeff King]

On Tue, Sep 27, 2011 at 11:28:14PM +0000, Michael Witten wrote:

>   With "git commit --no-parent", you would be altering the current
>   branch head, which means you are potentially leaving as a dangling
>   commit the commit to which that branch head originally pointed.
>   I.e., it is about as dangerous as "git reset --hard <new_root_commit>",
>   something for which we do NOT provide any protection.

Didn't I already mention that example? And then say that I think the
lack of protection there has been the source of a lot of confusion and
hardship?

Repeating the problems of "git reset" does not seem like a good idea to
me. Especially not with a command like "commit", which is usually very
safe.

That being said, I did say in my last email that one option would be for
the documentation to be very clear about leaving the old history
dangling. That at least keeps clueless people from stumbling into using
the option accidentally.

So I'm not saying "we can't do this". I'm saying "this is dangerous, so
let's think for a minute about what safety mechanisms we can have".

> For instance, what if I want the current branch head to point to that
> new root commit? The existing solution requires juggling branch names;
> why can't git just do what I tell it to do (as with "git reset")?
> After all, "git commit --no-parent" is pretty name explicit.

It's explicit if you understand how git works, or what "parent" means.
I'm not sure every git user does, these days.

-Peff

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

[Michael Witten]

On Tue, Sep 27, 2011 at 23:35, Jeff King <peff@peff.net> wrote:
> On Tue, Sep 27, 2011 at 11:28:14PM +0000, Michael Witten wrote:
>
>>   With "git commit --no-parent", you would be altering the current
>>   branch head, which means you are potentially leaving as a dangling
>>   commit the commit to which that branch head originally pointed.
>>   I.e., it is about as dangerous as "git reset --hard <new_root_commit>",
>>   something for which we do NOT provide any protection.
>
> Didn't I already mention that example? And then say that I think the
> lack of protection there has been the source of a lot of confusion and
> hardship?

Sorry, I suppose you did already mention that, but:

  * I missed it because of the footnote.
  * There is more pedantry to my text than just that.

> Repeating the problems of "git reset" does not seem like a good idea to
> me. Especially not with a command like "commit", which is usually very
> safe.

I think that "git reset" is confusing and dangerous for more
fundamental reasons: It's another one of git's bizarre, poorly
chosen abstractions on top of the working tree and index.

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

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Tue, Sep 27, 2011 at 11:28:14PM +0000, Michael Witten wrote:
>
>>   With "git commit --no-parent", you would be altering the current
>>   branch head, which means you are potentially leaving as a dangling
>>   commit the commit to which that branch head originally pointed.
>>   I.e., it is about as dangerous as "git reset --hard <new_root_commit>",
>>   something for which we do NOT provide any protection.
>
> Didn't I already mention that example? And then say that I think the
> lack of protection there has been the source of a lot of confusion and
> hardship?
>
> Repeating the problems of "git reset" does not seem like a good idea to
> me. Especially not with a command like "commit", which is usually very
> safe.
>
> That being said, I did say in my last email that one option would be for
> the documentation to be very clear about leaving the old history
> dangling. That at least keeps clueless people from stumbling into using
> the option accidentally.

Both of you are right and I agree "commit --root" is a bad idea (I can
change my mind ;-). Especially it is rare (and I would even say it should
be discouraged) to create a new root commit in a repository that already
has history, we should try to make it _very_ hard to lose history by
mistake, even though that means creating a new root commit has to be done
as a multi-step process (e.g. "checkout --orphan" to dissociate the new
state from the current history and then "commit").

Thanks for a bit of sanity.

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

[Jay Soffian]

On Tue, Sep 27, 2011 at 1:25 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Michael Witten <mfwitten@gmail.com> writes:
>
>> 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.
>
> This may indeed be an improvement. I suspect that we'd need to think about
> it a bit more, but it feels right (perhaps introduce this new option,
> deprecate --orphan from the checkout, and then eventually remove it
> sometime in 1.8.0 timeframe).

Hrm, create new_branch just so you can immediately clobber its SHA1
with the new commit that has no parents. That doesn't seem quite
right. Imagine you use "git commit --root" by accident while on
master, then you have to dig into your reflog?

But it's close. Maybe:

$ git commit --new-root-branch=<name>

Which creates <name> with the index as its sole commit and switches
you to that branch? That doesn't feel quite right either.

</thinking out loud>

j.

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

[Michael Witten]

On Wed, Sep 28, 2011 at 04:04, Jay Soffian <jaysoffian@gmail.com> wrote:
> On Tue, Sep 27, 2011 at 1:25 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> Michael Witten <mfwitten@gmail.com> writes:
>>
>>> 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.
>>
>> This may indeed be an improvement. I suspect that we'd need to think about
>> it a bit more, but it feels right (perhaps introduce this new option,
>> deprecate --orphan from the checkout, and then eventually remove it
>> sometime in 1.8.0 timeframe).
>
> Hrm, create new_branch just so you can immediately clobber its SHA1
> with the new commit that has no parents. That doesn't seem quite
> right.

The point is that users think about 2 things:

  * I need to create a root commit.
  * I need a branch head to point to that root commit,
    and I probably want a new branch head to do that.

My goal is to match the way people think; nobody thinks about the SHA1
when doing this task, and everybody thinks about creating a new branch
head.

More to the point, how is it better that "checkout --orphan" sets up
the working tree and index when the user is just going to obliterate
them or alter them significantly?

> Imagine you use "git commit --root" by accident while on
> master, then you have to dig into your reflog?

What's wrong with, say, "git reset --hard ORIG_HEAD"? (note that
ORIG_HEAD is already something understood by git).

> But it's close. Maybe:
>
> $ git commit --new-root-branch=<name>
>
> Which creates <name> with the index as its sole commit and switches
> you to that branch? That doesn't feel quite right either.

The "git commit" command shouldn't be canoodling the branch layer so intimately.

In fact, that's why I dislike:

  git checkout --orphan <branch_head>

The "--orphan" flag was no doubt added to "git checkout" because of
there already existed:

  git checkout -b <branch_head>

However, that is only available as a convenience (that is, a hack) for:

  git branch <branch_head>
  git checkout <branch_head>

It seems to be an even larger hack that "git checkout" as been given
so much control over setting the stage for not only the creation of a
branch head, but also the nature of the ancestry of the *next* commit.

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

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 27.09.2011 19:25:
> Michael Witten <mfwitten@gmail.com> writes:
> 
>> 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.
> 
> This may indeed be an improvement. I suspect that we'd need to think about
> it a bit more, but it feels right (perhaps introduce this new option,
> deprecate --orphan from the checkout, and then eventually remove it
> sometime in 1.8.0 timeframe).
> 
>>>>  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"?
> 
> I do not think "as in" is an improvement. It completely ignores the
> "Manipulate or not" part in the above, and "similar" was very much an

I do not see that part in the above. If you really "just run git commit
-a" after git branch --orphan you get the same tree.

> attempt to say "you do not have to commit it right away, but start from
> the state and commit a deviation of it".

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

[Michael Witten]

On Wed, Sep 28, 2011 at 00:32, Junio C Hamano <gitster@pobox.com> wrote:
> Jeff King <peff@peff.net> writes:
>
>> On Tue, Sep 27, 2011 at 11:28:14PM +0000, Michael Witten wrote:
>>
>>>   With "git commit --no-parent", you would be altering the current
>>>   branch head, which means you are potentially leaving as a dangling
>>>   commit the commit to which that branch head originally pointed.
>>>   I.e., it is about as dangerous as "git reset --hard <new_root_commit>",
>>>   something for which we do NOT provide any protection.
>>
>> Didn't I already mention that example? And then say that I think the
>> lack of protection there has been the source of a lot of confusion and
>> hardship?
>>
>> Repeating the problems of "git reset" does not seem like a good idea to
>> me. Especially not with a command like "commit", which is usually very
>> safe.
>>
>> That being said, I did say in my last email that one option would be for
>> the documentation to be very clear about leaving the old history
>> dangling. That at least keeps clueless people from stumbling into using
>> the option accidentally.
>
> Both of you are right and I agree "commit --root" is a bad idea (I can
> change my mind ;-). Especially it is rare (and I would even say it should
> be discouraged) to create a new root commit in a repository that already
> has history, we should try to make it _very_ hard to lose history by
> mistake, even though that means creating a new root commit has to be done
> as a multi-step process (e.g. "checkout --orphan" to dissociate the new
> state from the current history and then "commit").
>
> Thanks for a bit of sanity.

Well, I think Jeff already proferred a solution. We could have:

  git commit --no-parent

act like:

  git branch -d

in that it would require a "--force" when the commit to which the
current branch head points would be left dangling. In fact, we
could go one step further:

  git commit --no-parent

should require "--force" unless there exists another branch head
that points to the exact same commit as the current branch head; this
would tacitly enforce the notion that a new branch should be created
prior to the use of "--no-parent".

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

[Matthieu Moy]

Michael Witten <mfwitten@gmail.com> writes:

> Well, I think Jeff already proferred a solution. We could have:
>
>   git commit --no-parent
[...]

Appart from the safety objections, is the "root commit" senario common
enough to deserve appearing in the user-interface for both "commit" and
"checkout"?

I think "git commit -h" is scary enough as it is ...

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

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

[Michael Witten]

On Wed, Sep 28, 2011 at 13:45, Matthieu Moy
<Matthieu.Moy@grenoble-inp.fr> wrote:
> Michael Witten <mfwitten@gmail.com> writes:
>
>> Well, I think Jeff already proferred a solution. We could have:
>>
>>   git commit --no-parent
> [...]
>
> Appart from the safety objections, is the "root commit" senario common
> enough to deserve appearing in the user-interface for both "commit" and
> "checkout"?
>
> I think "git commit -h" is scary enough as it is ...

Well, as Junio mentioned, "--orphan" could be deprecated in favor of
"--no-parent"; the uncommon nature of this task works to our
advantage, in that it makes a deprecation of "--orphan" easy.

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

[Matthieu Moy]

Michael Witten <mfwitten@gmail.com> writes:

> Well, as Junio mentioned, "--orphan" could be deprecated in favor of
> "--no-parent"; the uncommon nature of this task works to our
> advantage, in that it makes a deprecation of "--orphan" easy.

I agree that _some_ cases would be more natural with commit --no-parent,
but I disagree that it is a better solution in general.

For example

# I want to create a new root commit with a different tree
git rm -fr *
vi file-in-new-project.txt
git add file-in-new-project.txt
# continue hacking for a while
git commit -m "New project" # oops, I forgot the --no-parent

History is not destroyed and you can still "git reset" back to the
previous commit, but you've at least temporarily damaged your branch
(and no --force flag could have prevented it). With "git checkout
--orphan" in the above scenario, you run the command at the time you
take the decision you want to create a root commit, and then hack
normally.

Even if you use it normally:

# I want to create a new root commit with a different tree
git checkout -b new-project
# hack for a while
git status
# ?!? why are files shown as 'deleted', 'moved', 'modified', I said I
# was creating a new project!

Also, with your proposal, we would need to add two flags to "commit"
(--no-parent and --force), which is one of the first command beginners
learn, while in the current state we have just one for "checkout" to do
the trick, and newbies do not use or read the doc for checkout, so it's
not scary for them.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

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

[Michael Witten]

On Wed, Sep 28, 2011 at 14:09, Matthieu Moy
<Matthieu.Moy@grenoble-inp.fr> wrote:

> Michael Witten <mfwitten@gmail.com> writes:
>
>> Well, as Junio mentioned, "--orphan" could be deprecated in favor of
>> "--no-parent"; the uncommon nature of this task works to our
>> advantage, in that it makes a deprecation of "--orphan" easy.
>
> I agree that _some_ cases would be more natural with commit --no-parent,
> but I disagree that it is a better solution in general.
>
> For example
>
> # I want to create a new root commit with a different tree
> git rm -fr *
> vi file-in-new-project.txt
> git add file-in-new-project.txt
> # continue hacking for a while
> git commit -m "New project" # oops, I forgot the --no-parent
>
> History is not destroyed and you can still "git reset" back to the
> previous commit, but you've at least temporarily damaged your branch
> (and no --force flag could have prevented it). With "git checkout
> --orphan" in the above scenario, you run the command at the time you
> take the decision you want to create a root commit, and then hack
> normally.
>
> Even if you use it normally:
>
> # I want to create a new root commit with a different tree
> git checkout -b new-project
> # hack for a while
> git status
> # ?!? why are files shown as 'deleted', 'moved', 'modified', I said I
> # was creating a new project!
>
> Also, with your proposal, we would need to add two flags to "commit"
> (--no-parent and --force), which is one of the first command beginners
> learn, while in the current state we have just one for "checkout" to do
> the trick, and newbies do not use or read the doc for checkout, so it's
> not scary for them.

Well, those are mildly interesting scenarios. I can only say that I don't
think we should cater to people who either have amnesia or work casually
on a repository for short bursts every few months or so.

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

[Matthieu Moy]

Michael Witten <mfwitten@gmail.com> writes:

>> Even if you use it normally:
>>
>> # I want to create a new root commit with a different tree
>> git checkout -b new-project
>> # hack for a while
>> git status
>> # ?!? why are files shown as 'deleted', 'moved', 'modified', I said I
>> # was creating a new project!
>>
>> Also, with your proposal, we would need to add two flags to "commit"
>> (--no-parent and --force), which is one of the first command beginners
>> learn, while in the current state we have just one for "checkout" to do
>> the trick, and newbies do not use or read the doc for checkout, so it's
>> not scary for them.
>
> Well, those are mildly interesting scenarios. I can only say that I don't
> think we should cater to people who either have amnesia or work casually
> on a repository for short bursts every few months or so.

How is the "git status" issue above linked to any kind of amnesia?

When hacking to create a rootless commit, it seems legitimate to me to
run "git status", and it seems _very_ confusing that "git status" still
refers to the commit you don't want as parent.

(I don't get the relation between your reply and the paragraph right
above it either)

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

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

[Michael Witten]

On Wed, Sep 28, 2011 at 14:45, Matthieu Moy
<Matthieu.Moy@grenoble-inp.fr> wrote:
> Michael Witten <mfwitten@gmail.com> writes:
>
>>> Even if you use it normally:
>>>
>>> # I want to create a new root commit with a different tree
>>> git checkout -b new-project
>>> # hack for a while
>>> git status
>>> # ?!? why are files shown as 'deleted', 'moved', 'modified', I said I
>>> # was creating a new project!
>>>
>>> Also, with your proposal, we would need to add two flags to "commit"
>>> (--no-parent and --force), which is one of the first command beginners
>>> learn, while in the current state we have just one for "checkout" to do
>>> the trick, and newbies do not use or read the doc for checkout, so it's
>>> not scary for them.
>>
>> Well, those are mildly interesting scenarios. I can only say that I don't
>> think we should cater to people who either have amnesia or work casually
>> on a repository for short bursts every few months or so.
>
> How is the "git status" issue above linked to any kind of amnesia?
>
> When hacking to create a rootless commit, it seems legitimate to me to
> run "git status", and it seems _very_ confusing that "git status" still
> refers to the commit you don't want as parent.

I think "confusing" is perhaps the wrong word. How about "annoying"?

I suppose it is true that neither "--orphan" nor "--no-parent" is good
enough alone. For instance:

  # I want to create a new root commit with a slightly different tree
  git checkout --orphan new-project
  # hack just a bit here and there
  git status
  # ?!? My slight alterations are obscured by hundreds of these
  #     "new file" status notifications!

> (I don't get the relation between your reply and the paragraph right
> above it either)

Is that a passive aggressive French way to state that I didn't respond
to your concern?

I think it's moot now, anyway, given that both "--orphan" and
"--no-parent" quite possibly have their logical purposes. However,
perhaps:

  git checkout --orphan

should be renamed:

  git checkout --no-parent

in order to match:

  git commit --no-parent

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

[Michael Witten]

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 |   65 +++++++++++++++++++++++++++------------
 1 files changed, 45 insertions(+), 20 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index c0a96e6..0b6e528 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -125,29 +125,54 @@ 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.
-+
-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.
-+
-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.
-+
-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.
-Afterwards you will be ready to prepare your new files, repopulating the
-working tree, by copying them from elsewhere, extracting a tarball, etc.
+--orphan::
+	Tell git to turn the next commit you create into a root commit
+	(that is, a commit without any parent); creating the next commit
+	is similar to creating the first commit after running "git{nbsp}init",
+	except that the new commit will be referenced by the branch head
+	<new_branch> rather than "master".
++
+Furthermore, the working tree and index are adjusted as if you ran
+"git{nbsp}checkout{nbsp}<start_point>"; thus, by just running
+"git{nbsp}commit", you can create a root commit with a tree that is
+exactly the same as the tree of <start_point>.
++
+Naturally, before creating the commit, you may manipulate the index
+in any way you want. For example, if you want to create a root commit
+with a tree that is totally different from the tree of <start_point>,
+then just clear the working tree and index first: From the top level
+of the working tree, run "git{nbsp}rm{nbsp}-rf{nbsp}.", and then
+prepare your new working tree and index as desired.
++
+There are two common uses for this option:
++
+--
+	Separate history::
+		Suppose that for convenience, you want to maintain
+		the website for your project in the same repository
+		as the project itself. In such a case, it may not
+		make much sense to interleave the history of the
+		website with the history of the project; you can use
+		the "--orphan" option in order to create these two
+		completely separate histories.
+
+	Hidden history::
+		Suppose you have a project that has proprietary
+		material that is never meant to be released to the
+		public, yet you now want to maintain an open source
+		history that may be published widely.
++
+In this case, it would not be enough just to remove the proprietary
+material from the working tree and then create a new commit, because
+the proprietary material would still be accessible through the new
+commit's ancestry; the proprietary history must be hidden from the new
+commit, and the "--orphan" option allows you to do so by ensuring that
+the new commit has no parent.
++
+However, removing proprietary material from ancestry is usually a task
+that is better performed by linkgit:git-filter-branch[1] and
+linkgit:git-rebase[1], especially when there are multiple commits that
+are already suitable for the open source history.
+--
 
 -m::
 --merge::
-- 
1.7.6.409.ge7a85

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

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

> Michael Witten <mfwitten@gmail.com> writes:
>
>> Well, as Junio mentioned, "--orphan" could be deprecated in favor of
>> "--no-parent"; the uncommon nature of this task works to our
>> advantage, in that it makes a deprecation of "--orphan" easy.
>
> I agree that _some_ cases would be more natural with commit --no-parent,
> but I disagree that it is a better solution in general.

Just for the record, in my later message after reading Peff's response, I
said I agree that adding it to "commit" would be a mistake.

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

[Junio C Hamano]

Michael Witten <mfwitten@gmail.com> writes:

> 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

I think I had to tell somebody on this list not to do this no more than a
month ago.

It is a good practice to point to earlier discussions while polishing
patch, and it also is good to include pointers in the commit log message
as a _supporting material_ (additional reading), but that is *NOT* a
substitute for a properly written commit log message. You need to state
what problem you are trying to fix and how the proposed patch fixes it.

Pretty please.

As to what the updated text wants to talk about, I think most of them are
improvement, but there are a few glitches and nits.

> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index c0a96e6..0b6e528 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -125,29 +125,54 @@ 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.
> -+
> -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.
> -+
> -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.
> -+
> -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.
> -Afterwards you will be ready to prepare your new files, repopulating the
> -working tree, by copying them from elsewhere, extracting a tarball, etc.
> +--orphan::
> +	Tell git to turn the next commit you create into a root commit
> +	(that is, a commit without any parent); creating the next commit
> +	is similar to creating the first commit after running "git{nbsp}init",

I do not think we ever used {nbsp} in our documentation set. Is it
absolutely necessary to use it in this context, and are you absolutely
sure this does not break various versions of documentation toolchain
people have?

> +	except that the new commit will be referenced by the branch head
> +	<new_branch> rather than "master".

The option works as a substitute for -B/-b in the sense that it takes a
name of the new branch, and the only difference is that the new branch
will start with no commit (yet).  To reduce confusion, it might make sense
to update this part (and description of -b/-B) to begin like this:

	--orphan <new_branch>::

to match the new explanation text, and the output from "git checkout -h".
By the way, shouldn't the entry for -b in "git checkout -h" output also
say <new branch>?

Micronit: "referenced by the branch head <new_branch>" might be easier to
read and understand with s/branch head/branch name/. Or perhaps

	except that the new commit will be made on <new_branch> branch
        rather than "master".

might be even better.

> ++
> +Furthermore, the working tree and index are adjusted as if you ran
> +"git{nbsp}checkout{nbsp}<start_point>"; thus, by just running
> +"git{nbsp}commit", you can create a root commit with a tree that is
> +exactly the same as the tree of <start_point>.
> ++
> +Naturally, before creating the commit, you may manipulate the index
> +in any way you want. ...

What value does "Naturally, " add to the understanding here? I would
understand if it were "Alternatively, ", though.

> +... For example, if you want to create a root commit
> +with a tree that is totally different from the tree of <start_point>,
> +then just clear the working tree and index first: From the top level
> +of the working tree, run "git{nbsp}rm{nbsp}-rf{nbsp}.", and then
> +prepare your new working tree and index as desired.
> ++
> +There are two common uses for this option:
> ++
> +--
> +	Separate history::
> +		Suppose that for convenience, you want to maintain
> +		the website for your project in the same repository
> +		as the project itself. In such a case, it may not
> +		make much sense to interleave the history of the
> +		website with the history of the project; you can use
> +		the "--orphan" option in order to create these two
> +		completely separate histories.

I suspect this is *not* common at all, and also because you would need a
working tree to update both lines of histories that are not related to
each other at all at the content level, I do not believe that "for
convenience" supports or justifies the use case at all. It would be less
convenient to update these two unrelated histories (switching between
branches would need to nuke the whole working tree, and the semantics to
carry local changes floating on top of the tip commit of the current
branch across branch switching actively works against you).

You would be better off using another repository to keep track of "the
website for your project".

In short, I do not think we would want to list the above as if we are
somehow encouraging the use of this option for such a use. It falls into
"because with --orphan you _could_", and definitely not "because having
these two unrelated projects in the same repository you work in is
convenient and/or necessary".

> +	Hidden history::
> +		Suppose you have a project that has proprietary
> +		material that is never meant to be released to the
> +		public, yet you now want to maintain an open source
> +		history that may be published widely.

This cause does make sense; you would want the local changes floating on
top of the tip commit of the current branch carried across branch
switching.

> +In this case, it would not be enough just to remove the proprietary
> +material from the working tree and then create a new commit, because
> +the proprietary material would still be accessible through the new
> +commit's ancestry; the proprietary history must be hidden from the new
> +commit, and the "--orphan" option allows you to do so by ensuring that
> +the new commit has no parent.

Does this "In this case" paragraph format as part of the "Hidden history"
paragraph?

> ++
> +However, removing proprietary material from ancestry is usually a task
> +that is better performed by linkgit:git-filter-branch[1] and
> +linkgit:git-rebase[1], especially when there are multiple commits that
> +are already suitable for the open source history.
> +--

In general it is true, and not "especially". When you are just abandoning
the history and publishing tidied up tree without history afresh.

I suspect this is not exactly "filter-branch is better but you could use
checkout --orphan" like you made it sound in the above paragraph.  If you
are bootstrapping a new open source project from the tip of a proprietary
tree, "checkout --orphan && edit to sanitize && commit" to start your
history afresh would be perfectly adequate for your PR people to say "Now
we are open", especially when you do not intend to accept fixes to older
revisions; you could filter-branch the older proprietary history but you
would not get much benefit out of the cost for doing so, I think.

Thanks.

[PATCH v4] Docs: git checkout --orphan: Copyedit, and s/root commit/orphan branch/

[Michael Witten]

It's copyediting; it's best just to read the damn patch, particularly when
there are no subtle details to be considered beyond the exhausting game of
making everybody involved in the email thread feel like he or she has gotten
a portion of the bikeshed painted a certain color.

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>

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/git-checkout.txt |   69 ++++++++++++++++++++++++++++-----------
 1 files changed, 49 insertions(+), 20 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index c0a96e6..bf042c2 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -125,29 +125,58 @@ 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.
-+
-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.
-+
-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.
-+
-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.
-Afterwards you will be ready to prepare your new files, repopulating the
-working tree, by copying them from elsewhere, extracting a tarball, etc.
+--orphan::
+	Perform these two tasks:
++
+--
+	* Adjust the working tree and index as if you ran
+	  "git checkout <start_point>".
+
+	* Set up git to turn the next commit you create into a root commit
+	  (that is, a commit without any parent); creating the next commit
+	  is similar to creating the first commit after running "git init",
+	  except that the new commit will be referenced by <new_branch>
+	  rather than "master".
+--
++
+Then, by just running "git commit", you can create a root commit
+with a tree that is exactly the same as the tree of <start_point>.
+Alternatively, before creating the commit, you may manipulate the
+index in any way you want; for example, to create a root commit with
+a tree that is totally different from the tree of <start_point>,
+just clear the working tree and index first: From the top level of
+the working tree, run "git rm -rf .", and then prepare your new
+working tree and index as desired.
++
+There are two common uses for this option:
++
+--
+	Separate history::
+		Suppose that for convenience, you want to maintain
+		in the same repository as your project some ancillary
+		material that is infrequently altered.  In such a case,
+		it may not make much sense to interleave the history of
+		that material with the history of your project; you can
+		use the "--orphan" option in order to create completely
+		separate histories.
+
+	Hidden history::
+		Suppose you have a project that has proprietary
+		material that is never meant to be released to the
+		public, yet you now want to maintain an open source
+		history that may be published widely.
++
+In this case, it would not be enough just to remove the proprietary
+material from the working tree and then create a new commit, because
+the proprietary material would still be accessible through the new
+commit's ancestry; the proprietary history must be hidden from the new
+commit, and the "--orphan" option allows you to do so by ensuring that
+the new commit has no parent.
++
+However, when there are multiple commits that are already suitable for
+the open source history (or that you want to make suitable), you should
+instead consider working with linkgit:git-filter-branch[1] and possibly
+linkgit:git-rebase[1].
+--
 
 -m::
 --merge::
-- 
1.7.6.409.ge7a85

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

[Michael Witten]

On Wed, 28 Sep 2011 13:34:22 -0700, Junio C Hamano wrote:

> As to what the updated text wants to talk about, I think most of them are
> improvement, but there are a few glitches and nits.
>
>> ...
>>
>> +--orphan::
>> +	Tell git to turn the next commit you create into a root commit
>> +	(that is, a commit without any parent); creating the next commit
>> +	is similar to creating the first commit after running "git{nbsp}init",
>
> I do not think we ever used {nbsp} in our documentation set. Is it
> absolutely necessary to use it in this context, and are you absolutely
> sure this does not break various versions of documentation toolchain
> people have?

I think it's absolutely necessary, but I'm not sure about how fragile
asciidoc is across versions with regard to this... I guess I'll remove
them.

>> +	except that the new commit will be referenced by the branch head
>> +	<new_branch> rather than "master".
>
> The option works as a substitute for -B/-b in the sense that it takes a
> name of the new branch, and the only difference is that the new branch
> will start with no commit (yet).  To reduce confusion, it might make sense
> to update this part (and description of -b/-B) to begin like this:
>
> 	--orphan <new_branch>::
>
> to match the new explanation text, and the output from "git checkout -h".
> By the way, shouldn't the entry for -b in "git checkout -h" output also
> say <new branch>?

I took the "<new_branch>" from the synopsis:

  SYNOPSIS
  --------
  [verse]
  'git checkout' [-q] [-f] [-m] [<branch>]
  'git checkout' [-q] [-f] [-m] [--detach] [<commit>]
  'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
  'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
  'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]

It would seem strange to include "<new_branch>" but not "<start_point>"
in each of the individual option descriptions.

In any case, I think we should leave that for another patch.

Moreover, I think it would be better to remove all `-h' output from
all git commands; they are always incomplete and/or different. Indeed,
at this point in history, programmers absolutely stink at writing
documentation, so it's probably a good idea just to centralize all
information as much as possible. Of course, I realize this suggestion
will never fly.

> Micronit: "referenced by the branch head <new_branch>" might be easier to
> read and understand with s/branch head/branch name/. Or perhaps
>
> 	except that the new commit will be made on <new_branch> branch
>         rather than "master".
>
> might be even better.

I have qualms with git's terminology, and using "branch head" as I have is
not only the closest thing to what I like, but it is also the only language
that is actually in complete agreement with git's own terminolgy as currently
defined by "git help glossary".

In the glossary, the term "branch name" only occurs once as part of:

  branch named "master"

which is undefined.

However, how skirting the whole issue:

  except that the new commit will be referenced by <new_branch>
  rather than "master".

>> +Furthermore, the working tree and index are adjusted as if you ran
>> +"git{nbsp}checkout{nbsp}<start_point>"; thus, by just running
>> +"git{nbsp}commit", you can create a root commit with a tree that is
>> +exactly the same as the tree of <start_point>.
>> ++
>> +Naturally, before creating the commit, you may manipulate the index
>> +in any way you want. ...
>
> What value does "Naturally, " add to the understanding here? I would
> understand if it were "Alternatively, ", though.

"Naturally" reassures the reader that nothing really special is happening
in terms of how the next commit can be made; there are no special cases.

"Alternatively" is too strong; these 2 paragraphs are not mutually
exclusive: The bit about running just "git commit" is only a
clarification of the preceding sentence.

Nevertheless, I have rearranged the text to use "Alternatively" in 
[PATCH v4]:

  Message-ID: <3cba6bb85bde4f96903b2b617190a2b8-mfwitten@gmail.com>
  Subject: [PATCH v4] Docs: git checkout --orphan: Copyedit,
			    and s/root commit/orphan branch/

It should be a reply to this email.

>> +... For example, if you want to create a root commit
>> +with a tree that is totally different from the tree of <start_point>,
>> +then just clear the working tree and index first: From the top level
>> +of the working tree, run "git{nbsp}rm{nbsp}-rf{nbsp}.", and then
>> +prepare your new working tree and index as desired.
>> ++
>> +There are two common uses for this option:
>> ++
>> +--
>> +	Separate history::
>> +		Suppose that for convenience, you want to maintain
>> +		the website for your project in the same repository
>> +		as the project itself. In such a case, it may not
>> +		make much sense to interleave the history of the
>> +		website with the history of the project; you can use
>> +		the "--orphan" option in order to create these two
>> +		completely separate histories.
>
> I suspect this is *not* common at all, and also because you would need a
> working tree to update both lines of histories that are not related to
> each other at all at the content level, I do not believe that "for
> convenience" supports or justifies the use case at all. It would be less
> convenient to update these two unrelated histories (switching between
> branches would need to nuke the whole working tree, and the semantics to
> carry local changes floating on top of the tip commit of the current
> branch across branch switching actively works against you).
>
> You would be better off using another repository to keep track of "the
> website for your project".
>
> In short, I do not think we would want to list the above as if we are
> somehow encouraging the use of this option for such a use. It falls into
> "because with --orphan you _could_", and definitely not "because having
> these two unrelated projects in the same repository you work in is
> convenient and/or necessary".

I was thinking of something like git's repo's "man", "html", and "todo",
but I was trying to express that along the lines of a more widely
recognizable scenario.

See [PATCH v4] for a more generic version.

>> +	Hidden history::
>> +		Suppose you have a project that has proprietary
>> +		material that is never meant to be released to the
>> +		public, yet you now want to maintain an open source
>> +		history that may be published widely.
>
> This cause does make sense; you would want the local changes floating on
> top of the tip commit of the current branch carried across branch
> switching.
>
>> +In this case, it would not be enough just to remove the proprietary
>> +material from the working tree and then create a new commit, because
>> +the proprietary material would still be accessible through the new
>> +commit's ancestry; the proprietary history must be hidden from the new
>> +commit, and the "--orphan" option allows you to do so by ensuring that
>> +the new commit has no parent.
>
> Does this "In this case" paragraph format as part of the "Hidden history"
> paragraph?

Yes. Have you no faith in me?

>> +However, removing proprietary material from ancestry is usually a task
>> +that is better performed by linkgit:git-filter-branch[1] and
>> +linkgit:git-rebase[1], especially when there are multiple commits that
>> +are already suitable for the open source history.
>> +--
>
> In general it is true, and not "especially".
> ...
> I suspect this is not exactly "filter-branch is better but you could use
> checkout --orphan" like you made it sound in the above paragraph.  If you
> are bootstrapping a new open source project from the tip of a proprietary
> tree, "checkout --orphan && edit to sanitize && commit" to start your
> history afresh would be perfectly adequate for your PR people to say "Now
> we are open", especially when you do not intend to accept fixes to older
> revisions; you could filter-branch the older proprietary history but you
> would not get much benefit out of the cost for doing so, I think.

I don't really see how what I wrote is fundamentally different. However,
I've rearranged it in [PATCH v4].

>> See:
>>
>>   Re: Can a git changeset be created with no parent
>>   Carlos Mart=C3=ADn 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
>
> I think I had to tell somebody on this list not to do this no more than a
> month ago.

What's your point?

> It is a good practice to point to earlier discussions while polishing
> patch, and it also is good to include pointers in the commit log message
> as a _supporting material_ (additional reading), but that is *NOT* a
> substitute for a properly written commit log message. You need to state
> what problem you are trying to fix and how the proposed patch fixes it.

That's a good rule of thumb. Although, interestingly, one my last code
patches for git was accompanied by a very detailed, precisely formulated
description of the problem and the solution, and yet it was dumbed down
behind my back.

In this case, though, I think the message title gives enough information,
particularly when combined with the diff: It's a commit that alters the
documentation for "git checkout --orphan", and somehow involves the terms
"root commit" and "branch head" (though no longer in [PATCH v4]); the rest
of the log message is just meant to be cake icing for the interested.

It's copyediting; it's best just to read the damn patch, particularly when
there are no subtle details to be considered beyond the exhausting game of
making everybody involved in the email thread feel like he or she has gotten
a portion of the bikeshed painted a certain color.

Hmmm... You know what? I think I'll make that last paragraph the message.

Sincerely,
Michael Witten

Re: [PATCH v4] Docs: git checkout --orphan: Copyedit, and s/root commit/orphan branch/

[Michael Witten]

On Thu, Sep 29, 2011 at 15:44, Michael Witten <mfwitten@gmail.com> wrote:

> Subject: [PATCH v4] Docs: git checkout --orphan: Copyedit, and s/root commit/orphan branch/

Do me the kind favor of replacing:

  s/root commit/orphan branch/

with:

  s/orphan branch/root commit/

Re: In favor of "git commit --no-parent"

[Junio C Hamano]

Michael Witten <mfwitten@gmail.com> writes:

> On Wed, 28 Sep 2011 13:34:22 -0700, Junio C Hamano wrote:
>
>> If you are bootstrapping a new open source project from the tip of a
>> proprietary tree, "checkout --orphan && edit to sanitize && commit" to
>> start your history afresh would be perfectly adequate for your PR people
>> to say "Now we are open".
>
> So, the two usages for a new root commit are:
>
>   * Separate History
>   * Hidden History

> As it turns out, the command:
>
>   git checkout --orphan
>
> which should be renamed:
>
>   git checkout --no-parent

I doubt that "should be" is anywhere near consensus.

> is best for the "Separate History" case,...

Step back a bit. There are two independent issues:

 - When does it make sense to originate two independent histories in a
   single repository that has a working tree?

 - What is the best tool to originate a new independent history in a
   single repository that has a working tree?

As I said number of times already, be it done with "checkout --orphan" or
"commit --no-parent", the "Separate History" use case is better done in a
separate repository. There is *no* advantage to originate the two separate
histories that do not share any resemblance of tree shape as branches in a
single repository with a working tree; "git checkout $branch" between the
two would actively work against you.

You are of course free to push from these separate repositories that have
disjoint roots of their own into a single distribution repository for
people to fetch from, if you want Separate Histories in a distribution
point.

That leaves "Hidden History" the only useful use case. IOW, the answer to
the first question above is not "Separate or Hidden History", but is
"Hidden History and nothing else".

And a half of the the answer to the second question is "checkout --orphan"
(and the other half would be "filter-branch"). "checkout --orphan" does
have major safety advantage than introducing "commit --no-parent", as Peff
pointed out earlier (to which I agreed).

Re: In favor of "git commit --no-parent"

[Michael Witten]

On Thu, Sep 29, 2011 at 18:11, Junio C Hamano <gitster@pobox.com> wrote:
> That leaves "Hidden History" the only useful use case. IOW, the answer to
> the first question above is not "Separate or Hidden History", but is
> "Hidden History and nothing else".
>
> And a half of the the answer to the second question is "checkout --orphan"
> (and the other half would be "filter-branch").

Uh... no.

If you think that "Hidden History" is all that matters, then you think that

  git commit --no-parent

is all that matters.

That's what my email was showing.

> "checkout --orphan" does
> have major safety advantage than introducing "commit --no-parent", as Peff
> pointed out earlier (to which I agreed).

Did I not provide in my previous email a decent safety mechanism?

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

[Junio C Hamano]

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

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

[Michael Witten]

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>

Re: [PATCH v4] Docs: git checkout --orphan: Copyedit, and s/root commit/orphan branch/

[Philip Oakley]

From: "Michael Witten" <mfwitten@gmail.com>
> It's copyediting; it's best just to read the damn patch, particularly when
> there are no subtle details to be considered beyond the exhausting game of
> making everybody involved in the email thread feel like he or she has 
> gotten
> a portion of the bikeshed painted a certain color.
>
> 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>
>
> Signed-off-by: Michael Witten <mfwitten@gmail.com>
> ---
> Documentation/git-checkout.txt |   69 
> ++++++++++++++++++++++++++++-----------
> 1 files changed, 49 insertions(+), 20 deletions(-)
>
> diff --git a/Documentation/git-checkout.txt 
> b/Documentation/git-checkout.txt
> index c0a96e6..bf042c2 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -125,29 +125,58 @@ 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.
> -+
> -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.
> -+
> -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.
> -+
> -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.
> -Afterwards you will be ready to prepare your new files, repopulating the
> -working tree, by copying them from elsewhere, extracting a tarball, etc.
> +--orphan::
> + Perform these two tasks:
> ++
> +--
> + * Adjust the working tree and index as if you ran
> +   "git checkout <start_point>".
> +
> + * Set up git to turn the next commit you create into a root commit
> +   (that is, a commit without any parent); creating the next commit
> +   is similar to creating the first commit after running "git init",
> +   except that the new commit will be referenced by <new_branch>
> +   rather than "master".
> +--
> ++
> +Then, by just running "git commit", you can create a root commit
> +with a tree that is exactly the same as the tree of <start_point>.
> +Alternatively, before creating the commit, you may manipulate the
> +index in any way you want; for example, to create a root commit with
> +a tree that is totally different from the tree of <start_point>,
> +just clear the working tree and index first: From the top level of
> +the working tree, run "git rm -rf .", and then prepare your new
> +working tree and index as desired.
> ++
> +There are two common uses for this option:
> ++
> +--
> + Separate history::

Can I suggest    "Distinct History::"    as this title.
'separate' is both a verb and a noun, and it is easy to misread the title as 
if it is the verb, which would then be describing the action of creating the 
hidden history (the second title), with resulting misunderstanding. 
"Distinct" avoids the problem. The use of 'seperate' at the end is in 
context,  so not an issue.

> + Suppose that for convenience, you want to maintain
> + in the same repository as your project some ancillary
> + material that is infrequently altered.  In such a case,
> + it may not make much sense to interleave the history of
> + that material with the history of your project; you can
> + use the "--orphan" option in order to create completely
> + separate histories.
> +
> + Hidden history::
> + Suppose you have a project that has proprietary
> + material that is never meant to be released to the
> + public, yet you now want to maintain an open source
> + history that may be published widely.
> ++
> +In this case, it would not be enough just to remove the proprietary
> +material from the working tree and then create a new commit, because
> +the proprietary material would still be accessible through the new
> +commit's ancestry; the proprietary history must be hidden from the new
> +commit, and the "--orphan" option allows you to do so by ensuring that
> +the new commit has no parent.
> ++
> +However, when there are multiple commits that are already suitable for
> +the open source history (or that you want to make suitable), you should
> +instead consider working with linkgit:git-filter-branch[1] and possibly
> +linkgit:git-rebase[1].
> +--
>
> -m::
> --merge::
> -- 
> 1.7.6.409.ge7a85
>

Re: In favor of "git commit --no-parent"

[Phil Hord]

On Thu, Sep 29, 2011 at 2:11 PM, Junio C Hamano <gitster@pobox.com> wrote:
[...]
> Step back a bit. There are two independent issues:
>
>  - When does it make sense to originate two independent histories in a
>   single repository that has a working tree?
>
>  - What is the best tool to originate a new independent history in a
>   single repository that has a working tree?
>
> As I said number of times already, be it done with "checkout --orphan" or
> "commit --no-parent", the "Separate History" use case is better done in a
> separate repository. There is *no* advantage to originate the two separate
> histories that do not share any resemblance of tree shape as branches in a
> single repository with a working tree; "git checkout $branch" between the
> two would actively work against you.

I think a user looking for this functionality -- either a new git user
or a user who seldom uses the "create secondary root commit" command
-- would first try 'git help init'.  It seems logical to me that I
should be able to do this:

 cd my-git-repo
 git init --root=<newbranch> .

This feels natural to me for this operation.

And it doesn't add "dangerous options" to the more commonly used
commands (checkout, commit)

[...]
> That leaves "Hidden History" the only useful use case. IOW, the answer to
> the first question above is not "Separate or Hidden History", but is
> "Hidden History and nothing else".

I think you're saying that the "hidden history" scenario is more
special than the "separate history" one because of these reasons:
1. It is already possible to create a "hidden history".

And that's it. No more reason than that.

But isn't it also possible already to create a "separate history" just
as easily?  I can think of at least three methods that do not involve
git-reset.  And I'm a relative newbie.

> And a half of the the answer to the second question is "checkout --orphan"
> (and the other half would be "filter-branch"). "checkout --orphan" does
> have major safety advantage than introducing "commit --no-parent", as Peff
> pointed out earlier (to which I agreed).

The thing I don't understand about "checkout --orphan" is exactly what
you're getting when you do this.  I assume you get a populated index
and a non-existent HEAD.  This seems a lot like "git init" to me,
especially in the non-existent HEAD area.

I didn't think git init would be much use for this scenario before,
but now I've changed my mind.

 git init --root=<newbranch> --keep-index

Again, this avoids complicating the common commands.  But maybe it
does overload init with extra baggage.

>From this user's perspective it still makes more sense.

Phil

p.s. Sorry for jumping in so late.

Re: In favor of "git commit --no-parent"

[Michael Witten]

On Thu, Sep 29, 2011 at 21:02, Phil Hord <phil.hord@gmail.com> wrote:
> On Thu, Sep 29, 2011 at 2:11 PM, Junio C Hamano <gitster@pobox.com> wrote:
> [...]
>> Step back a bit. There are two independent issues:
>>
>>  - When does it make sense to originate two independent histories in a
>>   single repository that has a working tree?
>>
>>  - What is the best tool to originate a new independent history in a
>>   single repository that has a working tree?
>>
>> As I said number of times already, be it done with "checkout --orphan" or
>> "commit --no-parent", the "Separate History" use case is better done in a
>> separate repository. There is *no* advantage to originate the two separate
>> histories that do not share any resemblance of tree shape as branches in a
>> single repository with a working tree; "git checkout $branch" between the
>> two would actively work against you.
>
> I think a user looking for this functionality -- either a new git user
> or a user who seldom uses the "create secondary root commit" command
> -- would first try 'git help init'.  It seems logical to me that I
> should be able to do this:
>
>  cd my-git-repo
>  git init --root=<newbranch> .
>
> This feels natural to me for this operation.

That would be a good place for the "git checkout --no-parent" variant,
especially given that I think "git checkout --no-parent" should produce
an empty working tree and index, which we can all note is essentially
what "git init" gives us.

Your suggestion seems like a corroboration of my stance.

Re: In favor of "git commit --no-parent"

[Phil Hord]

On Thu, Sep 29, 2011 at 5:28 PM, Michael Witten <mfwitten@gmail.com> wrote:
> On Thu, Sep 29, 2011 at 21:02, Phil Hord <phil.hord@gmail.com> wrote:
>> I think a user looking for this functionality -- either a new git user
>> or a user who seldom uses the "create secondary root commit" command
>> -- would first try 'git help init'.  It seems logical to me that I
>> should be able to do this:
>>
>>  cd my-git-repo
>>  git init --root=<newbranch> .
>>
>> This feels natural to me for this operation.
>
> That would be a good place for the "git checkout --no-parent" variant,
> especially given that I think "git checkout --no-parent" should produce
> an empty working tree and index, which we can all note is essentially
> what "git init" gives us.
>
> Your suggestion seems like a corroboration of my stance.

I'm not arguing the functionality; just the command spelling.
Consider your stance corroborated.

I don't like "git checkout" for this because
1. git-checkout is too popular already; oddball functions like this
should live in the shadows.
2. git-checkout is conceptually wrong, imho.  git-checkout means
"fetch me this commit" or "fetch me files from this commit".
Technically it does the same thing that we're talking about here (it
frobs the index, the workdir and HEAD), but conceptually it is very
different.

Conceptually, I think the functionality you're talking about is more
akin to git-init.

Phil

Re: In favor of "git commit --no-parent"

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Phil Hord <phil.hord@gmail.com> writes:
>
>> I think a user looking for this functionality -- either a new git user
>> or a user who seldom uses the "create secondary root commit" command
>> -- would first try 'git help init'.  It seems logical to me that I
>> should be able to do this:
>>
>>   cd my-git-repo
>>   git init --root=<newbranch> .
>>
>> This feels natural to me for this operation.
>
> Hmm, this does not feel very natural to me; unless "git init --root=work"
> uses 'work' branch instead of 'master' when creating a new repository,
> that is. But it is attractive that init is much less often used than
> checkout/commit and everybody knows it is somewhat a _special_ operation.
>
>>> That leaves "Hidden History" the only useful use case. IOW, the answer to
>>> the first question above is not "Separate or Hidden History", but is
>>> "Hidden History and nothing else".
>>
>> I think you're saying that the "hidden history" scenario is more
>> special than the "separate history" one because of these reasons:
>
> Not at all.
>
> I am saying that "separate history" has no place in git workflow, if these
> multiple roots _originate_ in the same single repository with a working
> tree. And all of "git checkout --orphan", "git commit --root" and your
> "git init --root" are solutions to make multiple roots _originate_ in the
> same single repository with a working tree.
>
> I have no trouble in a single repository with multiple roots if that is
> done in a distribution point, which by definition does not need and
> typically does not have any working tree. Options to "checkout/commit"
> would not help as they need a working tree.
>
> The way to do it is to work in multiple repositories, one for each of
> these roots, and push into a single repository from them.
>
>>> And a half of the the answer to the second question is "checkout --orphan"
>>> (and the other half would be "filter-branch"). "checkout --orphan" does
>>> have major safety advantage than introducing "commit --no-parent", as Peff
>>> pointed out earlier (to which I agreed).
>>
>> The thing I don't understand about "checkout --orphan" is exactly what
>> you're getting when you do this.  I assume you get a populated index
>> and a non-existent HEAD. This seems a lot like "git init" to me,
>> especially in the non-existent HEAD area.
>
> It is "HEAD pointing at a branch that does not yet exist", but I find it
> strangely attractive ;-)
>
>> I didn't think git init would be much use for this scenario before,
>> but now I've changed my mind.
>>
>>   git init --root=<newbranch> --keep-index
>>
>> Again, this avoids complicating the common commands.  But maybe it
>> does overload init with extra baggage.
>
> I do not think you would even need --keep-index there (running "git init"
> in an existing repository to see what it does. It does not touch the index
> nor HEAD).
>
> I am not sure if "--root" is the right name but if "git init --root=work"
> that is run to create (not re-init) a new repository points HEAD at a yet
> to be created 'work' branch instead of 'master', I think it would be a
> reasonable alternative.
>
> By the way, why did you drop the mailing list?

Re: In favor of "git commit --no-parent"

[Michael Witten]

On Thu, Sep 29, 2011 at 21:50, Phil Hord <phil.hord@gmail.com> wrote:
> On Thu, Sep 29, 2011 at 5:28 PM, Michael Witten <mfwitten@gmail.com> wrote:
>> On Thu, Sep 29, 2011 at 21:02, Phil Hord <phil.hord@gmail.com> wrote:
>>> I think a user looking for this functionality -- either a new git user
>>> or a user who seldom uses the "create secondary root commit" command
>>> -- would first try 'git help init'.  It seems logical to me that I
>>> should be able to do this:
>>>
>>>  cd my-git-repo
>>>  git init --root=<newbranch> .
>>>
>>> This feels natural to me for this operation.
>>
>> That would be a good place for the "git checkout --no-parent" variant,
>> especially given that I think "git checkout --no-parent" should produce
>> an empty working tree and index, which we can all note is essentially
>> what "git init" gives us.
>>
>> Your suggestion seems like a corroboration of my stance.
>
> I'm not arguing the functionality; just the command spelling.
> Consider your stance corroborated.
>
> I don't like "git checkout" for this because
> 1. git-checkout is too popular already; oddball functions like this
> should live in the shadows.
> 2. git-checkout is conceptually wrong, imho.  git-checkout means
> "fetch me this commit" or "fetch me files from this commit".
> Technically it does the same thing that we're talking about here (it
> frobs the index, the workdir and HEAD), but conceptually it is very
> different.
>
> Conceptually, I think the functionality you're talking about is more
> akin to git-init.

Actually, I'd say that the purpose of "git checkout" is to set the
working tree and index; in that sense, "git init" could in fact be
implemented by using "git checkout".

The key to what I'm saying, though, is that 2 scenarios are involved:

  * Make a root starting with nothing.
  * Make a root based off something.

The user should be able to express that, so that commands like
"git status" make sense. Currently, the user is only able
to express the first scenario:

  * Make a root starting with nothing.

but existing stuff is automatically added in case the user
wants to do the second scenario, but that makes "git status"
essentially unusuable for the second scenario, anyway.

Re: In favor of "git commit --no-parent"

[Phil Hord]

Junio C Hamano <gitster@pobox.com> writes:
> Phil Hord <phil.hord@gmail.com> writes:
>
>> I think a user looking for this functionality -- either a new git user
>> or a user who seldom uses the "create secondary root commit" command
>> -- would first try 'git help init'.  It seems logical to me that I
>> should be able to do this:
>>
>>   cd my-git-repo
>>   git init --root=<newbranch> .
>>
>> This feels natural to me for this operation.
>
> Hmm, this does not feel very natural to me; unless "git init --root=work"
> uses 'work' branch instead of 'master' when creating a new repository,
> that is. But it is attractive that init is much less often used than
> checkout/commit and everybody knows it is somewhat a _special_ operation.

That's what I meant.  Sorry my example wasn't more clear about that.
I also considered "--new-branch" and "--new-root".  I like the latter
more, but I didn't like the extra hyphen.  Considering the rarity and
the prior art, I guess either one is more clear here.

>>> That leaves "Hidden History" the only useful use case. IOW, the answer to
>>> the first question above is not "Separate or Hidden History", but is
>>> "Hidden History and nothing else".
>>
>> I think you're saying that the "hidden history" scenario is more
>> special than the "separate history" one because of these reasons:
>
> Not at all.
>
> I am saying that "separate history" has no place in git workflow, if these
> multiple roots _originate_ in the same single repository with a working
> tree.

No place in *your* workflow.  Oh, wait.  Except it has, and you use it
in the git tree.  So, um...  I'm confused.

> And all of "git checkout --orphan", "git commit --root" and your
> "git init --root" are solutions to make multiple roots _originate_ in the
> same single repository with a working tree.
>
> I have no trouble in a single repository with multiple roots if that is
> done in a distribution point, which by definition does not need and
> typically does not have any working tree. Options to "checkout/commit"
> would not help as they need a working tree.

I'm not sure where you're going with the "working tree" objection.
Are you saying that it's ok to _create_ "separate histories" in a bare
repository but wrong to do so in a non-bare one?  But surely this
means it is ok to _have_ "separate histories" in a non-bare
repository, since that is what I will get when I do a simple git-clone
of the bare one.

If I understand right, the mechanics of the initial creation is what
bothers you.  Is that right?  If so, we're on the same page here,
because it bothers me too.  The commit or checkout alternatives seem
like two halves of a turd sandwich.  Both ends are wrong somehow, and
it's because of the state of the working directory in the interim.

If I don't understand you right, ignore the sandwich metaphor and
please explain.

> The way to do it is to work in multiple repositories, one for each of
> these roots, and push into a single repository from them.

That's one way to do it.

>>> And a half of the the answer to the second question is "checkout --orphan"
>>> (and the other half would be "filter-branch"). "checkout --orphan" does
>>> have major safety advantage than introducing "commit --no-parent", as Peff
>>> pointed out earlier (to which I agreed).
>>
>> The thing I don't understand about "checkout --orphan" is exactly what
>> you're getting when you do this.  I assume you get a populated index
>> and a non-existent HEAD. This seems a lot like "git init" to me,
>> especially in the non-existent HEAD area.
>
> It is "HEAD pointing at a branch that does not yet exist", but I find it
> strangely attractive ;-)
>
>> I didn't think git init would be much use for this scenario before,
>> but now I've changed my mind.
>>
>>   git init --root=<newbranch> --keep-index
>>
>> Again, this avoids complicating the common commands.  But maybe it
>> does overload init with extra baggage.
>
> I do not think you would even need --keep-index there (running "git init"
> in an existing repository to see what it does. It does not touch the index
> nor HEAD).

In my imagined extension, the "separate history" action needs a clean
index.  I guess 'git rm -fr *' will suffice, but I think an in-line
switch would be more useful... for this "non-git workflow". :-)

> I am not sure if "--root" is the right name but if "git init --root=work"
> that is run to create (not re-init) a new repository points HEAD at a yet
> to be created 'work' branch instead of 'master', I think it would be a
> reasonable alternative.

That's what I meant.  How about this?

   git init --new-root-branch=<new-branch-name>

> By the way, why did you drop the mailing list?

Clicked the wrong button.  Not used to gmail yet for this.  Sorry about that.

Phil

Re: In favor of "git commit --no-parent"

[Michael Witten]

On Thu, Sep 29, 2011 at 21:54, Junio C Hamano <gitster@pobox.com> wrote:

> I am saying that "separate history" has no place in git workflow, if these
> multiple roots _originate_ in the same single repository with a working
> tree. And all of "git checkout --orphan", "git commit --root" and your
> "git init --root" are solutions to make multiple roots _originate_ in the
> same single repository with a working tree.

Why do you keep repeating this?

The "git commit --no-parent" is the CORRECT solution for
"HIDDEN history", NOT the "separate history" that you so loathe.

The existing "git checkout --orphan" is the CORRECT solution for
the "SEPARATE history" that you so loathe, NOT the "hidden history".

Re: In favor of "git commit --no-parent"

[Michael Witten]

On Thu, Sep 29, 2011 at 22:07, Phil Hord <phil.hord@gmail.com> wrote:
> If I understand right, the mechanics of the initial creation is what
> bothers you.  Is that right?  If so, we're on the same page here,
> because it bothers me too.  The commit or checkout alternatives seem
> like two halves of a turd sandwich.  Both ends are wrong somehow, and
> it's because of the state of the working directory in the interim.

Creating a Hidden History (Junio is OK with this usage):

  $ cd repo
  $ git checkout -b hidden-history
  $ # Hack away as usual or not
  $ git status # As with any other commit.
  $ git commit --no-parent

Creating a completely Separate History (Junio doesn't like this):

  $ cd repo
  $ git checkout --orphan separate-history
  $ git rm -rf . # This SHOULD be automatic.
  $ # add files as with an empty repo.
  $ git status # As with an empty new repo; lots of "new file"
  $ git commit

Those are the 2 halves, and they are correct for their purposes;
however, I would agree that "git init" is better instead of
"git checkout", especially when there should be an automatic
use of "git rm -rf .".

Consider trying the "Hidden History" scenario with the current
approach, which only allows for "git checkout --orphan":

  $ cd repo
  $ git checkout --orphan separate-history
  $ # Hack away as usual or not
  $ git status # lots of "new file" notifications obscuring my changes
  $ git commit

The main issue with "git commit --no-parent" is [supposedly] safety, but it
can be made pretty safe:

  $ cd repo
  $ # Hack away as usual or not
  $ git status # As with any other commit.
  $ git commit --no-parent
  Error! There must be another branch head directly referencing the
  same commit that is directly referenced by the current branch head!
  $ git checkout -b hidden-history
  $ git commit --no-parent

In the vast majority of cases, that rule will prevent people from
losing history inadvertantly, and no extra "--force" is required.

Re: In favor of "git commit --no-parent"

[Michael Witten]

On Thu, Sep 29, 2011 at 22:29, Michael Witten <mfwitten@gmail.com> wrote:

> Consider trying the "Hidden History" scenario with the current
> approach, which only allows for "git checkout --orphan":
>
>  $ cd repo
>  $ git checkout --orphan separate-history
>  $ # Hack away as usual or not
>  $ git status # lots of "new file" notifications obscuring my changes
>  $ git commit

To avoid confusion, please note that the line:

  $ git checkout --orphan separate-history

was meant to read:

  $ git checkout --orphan hidden-history

Re: In favor of "git commit --no-parent"

[Junio C Hamano]

Phil Hord <phil.hord@gmail.com> writes:

>> I am saying that "separate history" has no place in git workflow, if these
>> multiple roots _originate_ in the same single repository with a working
>> tree.
>
> No place in *your* workflow.  Oh, wait.  Except it has, and you use it
> in the git tree.  So, um...  I'm confused.

No, no place in anybody's workflow.

I do carry non source html/man branches in the same distribution point
repository, but I did not create and I do not have these unrelated
branches in my development repository. Possibility to run "git checkout
html" in my development repository is just insane.

The branch switching semantics of Git is designed to work well when all
the branches you check out in the working tree are somewhat related
content-wise. You create a new file, or make modifications to an existing
file, realize that the change wants to go to a branch different from the
current one. You _can_ switch to the branch the change should belong to,
because the contents in the working tree is defined to be not tied to any
branch, but is floating on top of the current branch.

We often see new people who do not understand this (yet) wonder "I
modified a file, switched to another branch, but the modification is still
there. Why?" It is because the local changes in the working tree do not
belong to a specific branch, and local changes could be committed to any
branch.

What would happen if I were crazy enough to have the html branch in my
development repository and checked it out? In addition to the previous
build artifacts *.o files, new source files *.[ch] and documentation
sources Documentation/*.txt will stay and will be mixed in the checkout of
the html branch, where we all know there is no reason for them to be
committed on.

A sane way to use Git is to have a separate repository to keep track of
changes in the other unrelated material, and I have separate repositories
with checkouts for html and man. Of course I do not edit them manually;
these repositories are targets of "make install-doc" from the source
repository.

They happen to be pushed into the same distribution point repository, but
that is a mere historical artifact. It only started because at k.org I
only had a write access to /pub/scm/git/git.git but not to /pub/scm/git/
directory itself; I may have used /pub/scm/git/html and /pub/scm/git/man
repositories otherwise. 

And cloners are advised to "tar-tree" these out and extract them to
somewhere else, if they do not want to format the documentation themselves
but still want to look at them. Of course, they could "checkout", but you
would not edit these generated files in the working tree or commit to
these branches. So in that sense, yes they could "checkout", but that is
like saying they can run "rm -fr .git" too---they can do useful things and
not so useful things just alike.

I suspect that people often see those html/man branches in the
distribution point repository and get a wrong idea that having these
unrelated histories somehow add their coolness factor. It doesn't.

>> I have no trouble in a single repository with multiple roots if that is
>> done in a distribution point, which by definition does not need and
>> typically does not have any working tree. Options to "checkout/commit"
>> would not help as they need a working tree.
> ...
>> The way to do it is to work in multiple repositories, one for each of
>> these roots, and push into a single repository from them.
>
> That's one way to do it.

And I have been trying to teach why the other way is a wrong thing to do,
but there is no point in teaching a better practice if the listener is not
willing to learn. My time is better spent on other topics.

Re: In favor of "git commit --no-parent"

[Michael Witten]

On Thu, Sep 29, 2011 at 23:08, Junio C Hamano <gitster@pobox.com> wrote:

> The branch switching semantics of Git is designed to work well when all
> the branches you check out in the working tree are somewhat related
> content-wise. You create a new file, or make modifications to an existing
> file, realize that the change wants to go to a branch different from the
> current one. You _can_ switch to the branch the change should belong to,
> because the contents in the working tree is defined to be not tied to any
> branch, but is floating on top of the current branch.

That's exactly why "git commit --no-parent" is so useful.

Look at the difference:

  Creating a Hidden History (git commit --no-parent)

    $ cd repo
    $ git checkout -b hidden-history
    $ # Hack away as usual or not
    $ git status # As with any other commit.
    $ git commit --no-parent

  Creating a Hidden History (git checkout --orphan):

    $ cd repo
    $ git checkout --orphan hidden-history
    $ # Hack away as usual or not
    $ git status # lots of "new file" notifications obscuring my changes
    $ git commit

The main issue with "git commit --no-parent" is [supposedly] safety, but it
can be made pretty safe:

  $ cd repo
  $ # Hack away as usual or not
  $ git status # As with any other commit.
  $ git commit --no-parent
  Error! There must be another branch head directly referencing the
  same commit that is directly referenced by the current branch head!
  $ git checkout -b hidden-history
  $ git commit --no-parent

In the vast majority of cases, that rule will prevent people from
losing history inadvertantly, and no extra "--force" is required.

Re: In favor of "git commit --no-parent"

[Junio C Hamano]

Michael Witten <mfwitten@gmail.com> writes:

> The main issue with "git commit --no-parent" is [supposedly] safety, but it
> can be made pretty safe:
>
>   $ cd repo
>   $ # Hack away as usual or not
>   $ git status # As with any other commit.
>   $ git commit --no-parent
>   Error! There must be another branch head directly referencing the
>   same commit that is directly referenced by the current branch head!

That safety indeed will work, and I kind of like it. I think this is in
line with what we try to do when you come back from a detached HEAD state.

You may also want to allow this when HEAD is detached already (I am just
thinking aloud here). One possible workflow may be to start from somewhere
random, such as the last customer release point:

	git checkout rel-2011-09-01
        # strip proprietary stuff away
	# make sure the result is satisfactory
	git commit --no-parent
        git checkout -b opensource

By the way, I am not convinced enough with the "git status" argument,
though.

The output from "status" and "diff" will show what you changed, but in the
"strip proprietary stuff" scenario, what you care much more about is what
you forgot to remove.

If my current source is littered with a confidencial name of an unreleased
device that I need to remove, I am more likely to use "git grep" on the
_remaining_ files, and this does not make a difference between "checkout
--orphan" or "commit --no-parent".

But I would imagine I would not _know_ what I am looking for until I see
it. There may be the name of another confidential device in the source
that I need to sanitize, too.

In a "strip" scenario, I suspect that the most natural way to verify would
be to run "git diff" between what is about to be committed and an empty
tree and inspect the output. That would be what I would do if I were
starting from an empty repository, populating the working tree and the
index with what I think is releaseable.

Another an advantage of "commit --no-parent" is that we do not have to
worry about a corner case like this:

	git checkout --orphan xyzzy
        # time passes, you do many things
        git checkout foo
	git branch | grep xyzzy ;# not found -- what happened to the branch?