From: Michael Witten Date: Tue, 27 Sep 2011 16:02:32 GMT Subject: Re: [PATCH] Docs: git checkout --orphan: `root commit' and `branch head' Message-ID: In-Reply-To: <4E81F080.7010905@drmicha.warpmail.net> On Tue, Sep 27, 2011 at 15:49, Michael J Gruber 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 >>   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 >> --- >>  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 , started from >> -     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 . > > 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 ".  This allows you to start a new history >> -that records a set of paths similar to by easily running >> +that records a set of paths similar to 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.