Re: [PATCH v3] git checkout -b: unparent the new branch with -o

Erick Mattos [off-list ref] writes:

I am just trying to make you satisfied so gitsters, I mean git users,
will have this feature as soon as possible.

Don't try to satisfy _me_ personally.  It is not likely that I am going to
use "checkout --orphan" myself.  But I would not reject a new feature that
does make sense to some people, even if it is not something I would use.
I am here to help people like you help others (and to prevent people from
harming others).

I however am going to have to answer when people complain "why was this
senseless new feature added to the system?  what it does makes no sense
and does not help me."

"Nuke index but not working tree" is not something I think I can defend
and explain as sensible to these people, as I do not think it makes sense
myself.  So when Ispot a design that logically does not make sense to me,
I would say so and ask clarifications.  A major part of the maintainer's
job is to ask questions and say "no".

I do prefer my first design mainly because it mimics the state of an
initial commit.  I think that is subjectively better.

You keep saying that, but I think it is misguided.  And I do not think
there is anything subjective there.

If you are starting from scratch, you would:

    $ git init newrepo
    $ cd newrepo

and that is how the state before the initial commit begins with.  You
might then do this to prepare for the commit:

    $ tar xf ~/junk/frotz-2.43.tar.gz
    $ git add .

Or perhaps you would work the other way around:

    $ tar xf ~/junk/frotz-2.43.tar.gz
    $ cd frotz-2.43
    $ git init
    $ git add .

Whichever way you work, notice that you wouldn't have any rubbish in the
working tree unrelated to the "frotz" project, when the tool (in this
case, "git init") prepares the repository with a dangling HEAD and the
working tree "before the initial commit".  You either have emptiness (to
which you can untar into), or you already have files that you would want
to have in the branch and no other cruft.

If you did "nuke index, leaving files in the work tree around", the result
does not resemble "state before the initial commit" at all.  The leftover
files will get in the way.

The leftover worktree files will not get in the way ONLY if the user wants
to record a tree that is similar to the original branch, but even in that
case they have to do "git add ."; keeping the index intact would help them
even better.

After realizing all that, do you still think "nuke only the index" is
subjectively better?

I did it!

Sure, I am saying that then you should advertise the result as such,
without being negative.

quoted

Better yet, try to advertise what you are giving your users in a positive
way, instead of in a way that only scares users, perhaps like this:

   After 'checkout --orphan', your HEAD will point at an unborn branch,
   and the next commit will start a new history without any prior commit.
   To help create such a new history that has contents mostly the same as
   that of the original branch, the command does not touch the index nor
   the working tree, and "checkout --orphan" immediately followed by
   "commit -a" would record a tree very similar to what you had in the
   original branch.  This is useful when you want to ... [insert a
   summary of "going open source" example from my previous message if you
   want here].

   If on the other hand you want to start a new branch whose contents do
   not resemble the original branch at all, you may want to start from an
   empty index and the working tree, with "git rm -rf ." immediately
   after running this command.

The same comment applies to the documentation part.

I was trying to be concise on my message.  I realize you want it more explained.

Concise is good.  Negative is not.

After the 'checkout -o -b' you are in an new unborn branch ready to be
committed.  The next commit will start a new history without any
ancestry.  If this new branch was made to start from scratch, not
resembling the previous one, then you should use 'git rm -rf' to get
an empty work tree and index.  Otherwise with a 'git commit -a' you
will have a tree exactly as in the previous branch.  So just set
things as you want it to be and commit the new unparented branch.

I wouldn't start the description with

    if you want 'no common paths', then it would be more cumbersome than
    just this single command

if the primary workflow your chose to support with your implementation is
'mostly common paths'.

Look at the example I gave you more carefully.  The primary use case we
intend to support is described first.  Also it is written in much more
inviting tone, in order to help readers understand the motivation behind
the feature.  IOW, "Ah, that is something I may want to do in some cases,
and the new feature indeed sounds useful." is what we want to hear from
the readers (the log message for reviewers, and the documentation for the
end users) after they read the explanation.  The second paragraph then
mentions the less common use case for completeness.  To the readers who
understand why the behaviour of the command makes sense for its primary
use case (which is described first), it would be easier to accept that
they have to run an extra command (by the way, it is "'git rm -rf .' from
the top-level of the working tree; do not forget the dot at the end) to
clean up the working tree to a prestine state, because they would
understand the reason why the clearing is not done by default.

The same comment applies to the documentation part of the patch.  Don't be
negative.  Positively explain why what you added is useful, and help the
users understand why they might want to use it and in what situation.