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

On Tue, Sep 27, 2011 at 15:49, Michael J Gruber
[off-list ref] wrote:

Michael Witten venit, vidit, dixit 27.09.2011 16:43:

quoted

See:

  Re: Can a git changeset be created with no parent
  Carlos Martín Nieto [off-list ref]
  Message-ID: [ref]
  http://article.gmane.org/gmane.comp.version-control.git/182170

and:

  git help glossary

Signed-off-by: Michael Witten <redacted>
---
 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

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

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

quoted

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