Re: [RFC] Introduce two new commands, switch-branch and restore-paths

From: Stefan Beller <sbeller@google.com>
Date: Nov 26, 2018, 23:10 UTC
Message-ID: <CAGZ79kaCidJ1s2vXaQX9b_o7Tk4O+WTdmBSM3RBKX3bCBMSFKA@mail.gmail.com>
In-Reply-To: <87o9abzv46.fsf@evledraar.gmail.com>

On Mon, Nov 26, 2018 at 8:01 AM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:

Show 20 quoted lines

>
>
> On Tue, Nov 20 2018, Duy Nguyen wrote:
>
> > On Mon, Nov 19, 2018 at 04:19:53PM +0100, Duy Nguyen wrote:
> >> I promise to come back with something better (at least it still
> >> sounds better in my mind). If that idea does not work out, we can
> >> come back and see if we can improve this.
> >
> > So this is it. The patch isn't pretty, mostly as a proof of
> > concept. Just look at the three functions at the bottom of checkout.c,
> > which is the main thing.
> >
> > This patch tries to split "git checkout" command in two new ones:
> >
> > - git switch-branch is all about switching branches
>
> Isn't this going to also take the other ref arguments 'git checkout'
> takes now? I.e. tags, detached HEADs etc? I'm reminded of the discussion
> about what "range-diff" should be called :)

Heh, good call. :-) Note that the color of a bikeshed has fewer functional implications than coming up with proper names in your API exposed to millions of users, as cognitive associations playing mind tricks, can have a huge impact on their productivity. ;-)

In a neighboring thread there is discussion of the concept of a 'change' (and evolving the change locally), which is yet another thing in the refs-space.

'switch-branch' sounds like a good name for a beginner who is just getting started, but as soon as they discover that there is more than branches (detached HEAD via commits, tags, remote tracking "branches"), this name may be confusing. So it would not be a good choice for the intermediate Git user. The old time power user would not care as they have 'checkout' in their muscle memory, aliased to 'co', but maybe they'd find it nice for explaining to new users.

So I'd be thrilled to find a name that serves users on all levels.

Maybe we need to step back and consider what the command does. And from that I would name it "rewire-HEAD-and-update-index&worktree" and then simplify from there. For the beginner user, the concept of HEAD might be overwhelming, such that we don't want to have that in there.

So I'd be tempted to suggest to call it "switch-to-ref", but that would be wrong in the corner case as well: When using that with a remote tracking branch, you don't "switch to it" by putting it into your HEAD, but you merely checkout the commit that it's pointing at.

>
> > - git restore-paths (maybe restore-file is better) for checking out
> >   paths

"content-to-path", maybe(?) as it moves the content (as given by commit or implicitly assuming the index when omitted) into that path(, again). (I am not enthused about this, as you can similarly argue for content-to-paths, content-to-worktree, which then could split up into "index-to-worktree [pathspec]" as well as "tree-to-worktree <commit>". also the notion of X-to-Y seems a novel concept in our naming, so maybe verb-noun is better, hence restore-path or "fix-paths" may be better)

Show 5 quoted lines

> > Later on, we could start to add a bit more stuff in, e.g. some form of
> > disambiguation is no longer needed when running as switch-branch, or
> > restore-paths.
> >
> > So, what do you think?

The patch looks interestingly small :-)

Show 9 quoted lines

> That "git checkout" does too many things is something that keeps coming
> up in online discussions about Git's UI. Two things:
>
> a) It would really help to have some comparison of cases where these
>    split commands are much clearer or less ambiguous than
>    git-checkout. I can think of some (e.g. branch with the same name as
>    a file) but having some overall picture of what the new UI looks like
>    with solved / not solved cases would be nice. Also a comparison with
>    other SCMs people find less confusing (svn, hg, bzr, ...)

How do other SCMs solve this issue? (What is their design space? How many commands do they have for what git-checkout does all-in-one?)

Show 5 quoted lines

> b) I think we really need to have some end-game where we'd actually
>    switch away from "checkout" (which we could still auto-route to new
>    commands in perpetuity, but print a warning or error). Otherwise
>    we'll just end up with https://xkcd.com/927/ and more UI confusion
>    for all.

Heh, that situation is only avoided when the new command has clear advantages over the old, and ISTM that we can only compete on UX and better defaults, so maybe I'd push for making it more logical, maybe so:

  git tree-to-worktree # git checkout <commit> -- <path>
  git index-to-worktree # git checkout -- <path>
  git rev-to-ref # git checkout <commit>

Just food for thought, specifically the last one would be hilarious if we'd end up with it.

Stefan