Re: [PATCH v3 10/21] checkout: split part of it to new command 'switch'

[Elijah Newren <newren@gmail.com>]

On Sun, Mar 17, 2019 at 7:03 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Elijah Newren <newren@gmail.com> writes:
>
> > I don't see why <start-point> even makes sense to use with --orphan;
> > you should error if both are given, IMO.  The point of --orphan is to
> > create some entirely new history.  So, I'd expect "git switch --orphan
> > <new-branch>" to:
> >   * not create refs/heads/<new-branch>
> >   * set HEAD to refs/heads/<new-branch>
> >   * empty all tracked files from the working tree.
> >   * empty the index
> >
> > Alternatively, you could allow <start-point> to be passed with
> > --orphan, adjusting the above steps so that both the index and the
> > working tree are switched to match <start-point>, but ONLY if
> > <start-point> defaults to the empty tree when --orphan is passed.
>
> Do you mean that it's like <start-point> is not really a start-point
> but is an initial tree, i.e.
>
>         switch --orphan --initial-tree=<tree-ish> <new-branch>
>
> is a mere short-hand for
>
>         switch --orphan <new-branch> &&
>         restore --from-tree=<tree-ish> .

Yes.

> I think that does make sense, but at the same time, I think a major
> reason why people say "checkout does too many things depending on
> the arguments and conext to be easily explained" is exactly due to
> its many "if you give X, it is like writing this longer command
> sequence" short hands, so...

Yes, this is a concern for me too.  I would be happier if we made
--orphan and <start-point> incompatible and avoided the need to
explain how they worked together.  Besides, as you point out, the
wording is bad and should instead be a separate option named
--initial-tree=<tree-ish> which people will then start asking us to
allow them to specify even in cases when --orphan isn't (e.g. `git
switch --initial-tree=HEAD maint`), which is a weird/esoteric usecase
that is probably better served by using separate commands.

> > How about:
> >
> > """
> > Switching and creating branches always involves knowing the
> > <start-point> to begin the new branch from.  Sometimes, people want to
> > create a new branch that does not have any commits yet; --orphan is a
> > flag to allow that.  --orphan overrides the default of HEAD for
> > <start-point> instead causing us to start from an empty history.  The
> > use of --orphan is incompatible with specifying a <start-point>.
> > """
>
> With or without the short-hand to say which initial tree to populate
> the index from, the above description makes sense to me.

Yeah, perhaps "...an empty history with all tracked files removed from
the index and working tree.  The use of..."