Re: [PATCH] worktree: add shorthand '-d' for detach

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Jan 27, 2020, 16:05 UTC
Message-ID: <CAPig+cS_H+FTcZkBz4dA94bAcxv0CZ8UG=P8jOGvD=HXzf8ODQ@mail.gmail.com>
In-Reply-To: <20200127122610.GB10482@szeder.dev>

On Mon, Jan 27, 2020 at 7:26 AM SZEDER Gábor <szeder.dev@gmail.com> wrote:

Show 21 quoted lines

> On Sat, Jan 25, 2020 at 11:07:44PM +0530, Pratyush Yadav wrote:
> > Often someone might want to checkout an older commit in a separate
> > worktree to test it out without having any intention of making any
> > changes. Simply using 'git worktree add' means that a branch will be
> > created based on the name of the worktree folder. This branch will then
> > have to be deleted by the user once they are done with the worktree.
> >
> > An alternative to this is to create a detached worktree which doesn't
> > lead to a branch being created. This can be done by the '--detach'
> > option. Add the shorthand to make it more convenient to use it.
>
> I don't really understand what this commit message is trying to say,
> especially the first paragraph, or how it relates to adding short
> options.
>
> It could just say something along the lines of "'git worktree add' has
> a couple of long --options without corresponding -o short options, you
> wanted to type less, so let's add those missing short options."
>
> But then why only '--detach', and not the other long --options as
> well?

To answer this, it probably would make more sense to bundle this change together with one which (from [1]):

    [...] improves git-worktree documentation to do a better job of
    pointing people at -d/--detach as a way to side-step unwanted
    branch creation [...]. That is, at minimum, enhance the
    "Description" section to prominently talk about throwaway
    worktrees (created with -d/--detach), and add an example to the
    "Examples" section (perhaps as the first example) showing
    creation/use/deletion of a throwaway worktree.

Toward that goal, adding the '-d' alias for '--detach' helps promote throwaway worktrees as a first-class concept supported by git-worktree. As mentioned in [1]:

    "git worktree add -d foo" is about as easy to type and remember as
    "git worktree add foo"

[1]: https://lore.kernel.org/git/CAPig+cQmqKiYWDWFH5eK2S6XPOi2t2+8Oas8yZa8R=bKLym3wQ@mail.gmail.com/

Show 5 quoted lines

> > -'git worktree add' [-f] [--detach] [--checkout] [--lock] [-b <new-branch>] <path> [<commit-ish>]
> > +'git worktree add' [-f] [-d] [--checkout] [--lock] [-b <new-branch>] <path> [<commit-ish>]
>
> '--detach' is still an accepted options, so please write it as
> '[-d|--detach]' instead.

I'd have no problem leaving this as '[--detach]'; readers can discover the short alias easily enough where '--detach' is discussed without mentioning it here.

Show 6 quoted lines

> > If <commit-ish> is a branch name (call it `<branch>`) and is not found,
> > -and neither `-b` nor `-B` nor `--detach` are used, but there does
> > +and neither `-b` nor `-B` nor `-d` are used, but there does
>
> Here I would prefer to keep '--detach', because "detach" is a real
> word with proper meaning, while 'd' is just an abbreviation.

I fully agree with this assessment and was going to say the same. '-b' and '-B' are special in that they don't have corresponding long option names, thus they must be shown in short form, but long name '--detach' is much more informative in this context (and the reader can discover short '-d' easily enough without mentioning it here). So, I'd drop this change (and the other similar one).