On Mon, Jan 27, 2020 at 7:26 AM SZEDER Gábor <szeder.dev@xxxxxxxxx> wrote:
> 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@xxxxxxxxxxxxxx/
> > -'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.
> > 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).
