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

On Mon, Jan 27, 2020 at 7:26 AM SZEDER Gábor [off-list ref] wrote:

On Sat, Jan 25, 2020 at 11:07:44PM +0530, Pratyush Yadav wrote:

quoted

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/ (local)

quoted

-'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.

quoted

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).