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

Michael Witten [off-list ref] 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).

quoted

quoted

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

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

Michael Witten [off-list ref] writes:

quoted

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

quoted

quoted

quoted

 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.

On 11:59 AM, Junio C Hamano wrote:

Michael Witten [off-list ref] writes:

quoted

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.

From: "Eric Raible" <redacted>

On 11:59 AM, Junio C Hamano wrote:

quoted

Michael Witten [off-list ref] writes:

quoted

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

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

quoted

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.

On Tue, Sep 27, 2011 at 21:42, Jeff King [off-list ref] 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.

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

On Tue, Sep 27, 2011 at 23:35, Jeff King [off-list ref] wrote:

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

quoted

  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.

On Tue, Sep 27, 2011 at 1:25 PM, Junio C Hamano [off-list ref] wrote:

Michael Witten [off-list ref] writes:

quoted

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.

On Wed, Sep 28, 2011 at 04:04, Jay Soffian [off-list ref] wrote:

On Tue, Sep 27, 2011 at 1:25 PM, Junio C Hamano [off-list ref] wrote:

quoted

Michael Witten [off-list ref] writes:

quoted

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.

Junio C Hamano venit, vidit, dixit 27.09.2011 19:25:

Michael Witten [off-list ref] writes:

quoted

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

quoted

quoted

quoted

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