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

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.