On Thu, Sep 29, 2011 at 18:59, Junio C Hamano <gitster@xxxxxxxxx> 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@xxxxxxxxx> > --- > > * 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@xxxxxxxxx> -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html