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

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

[Pratyush Yadav]

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.

Signed-off-by: Pratyush Yadav <me@yadavpratyush.com>
---
For more context:
https://lore.kernel.org/git/CAPig+cQmqKiYWDWFH5eK2S6XPOi2t2+8Oas8yZa8R=bKLym3wQ@mail.gmail.com/

I'll send a patch to add the config option as a follow up some time
later.

 Documentation/git-worktree.txt | 7 ++++---
 builtin/worktree.c             | 2 +-
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 85d92c9761..cc227dd382 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -9,7 +9,7 @@ git-worktree - Manage multiple working trees
 SYNOPSIS
 --------
 [verse]
-'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>]
 'git worktree list' [--porcelain]
 'git worktree lock' [--reason <string>] <worktree>
 'git worktree move' <worktree> <new-path>
@@ -52,7 +52,7 @@ directory specific files such as HEAD, index, etc. `-` may also be
 specified as `<commit-ish>`; it is synonymous with `@{-1}`.
 +
 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
 exist a tracking branch in exactly one remote (call it `<remote>`)
 with a matching name, treat as equivalent to:
 +
@@ -69,7 +69,7 @@ branches from there if `<branch>` is ambiguous but exists on the
 'origin' remote. See also `checkout.defaultRemote` in
 linkgit:git-config[1].
 +
-If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used,
+If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `-d` used,
 then, as a convenience, the new worktree is associated with a branch
 (call it `<branch>`) named after `$(basename <path>)`.  If `<branch>`
 doesn't exist, a new branch based on HEAD is automatically created as
@@ -140,6 +140,7 @@ To remove a locked working tree, specify `--force` twice.
 	exists. `-B` overrides this safeguard, resetting `<new-branch>` to
 	`<commit-ish>`.

+-d::
 --detach::
 	With `add`, detach HEAD in the new working tree. See "DETACHED HEAD"
 	in linkgit:git-checkout[1].
diff --git a/builtin/worktree.c b/builtin/worktree.c
index d6bc5263f1..dab5f76788 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -500,7 +500,7 @@ static int add(int ac, const char **av, const char *prefix)
 			   N_("create a new branch")),
 		OPT_STRING('B', NULL, &new_branch_force, N_("branch"),
 			   N_("create or reset a branch")),
-		OPT_BOOL(0, "detach", &opts.detach, N_("detach HEAD at named commit")),
+		OPT_BOOL('d', "detach", &opts.detach, N_("detach HEAD at named commit")),
 		OPT_BOOL(0, "checkout", &opts.checkout, N_("populate the new working tree")),
 		OPT_BOOL(0, "lock", &opts.keep_locked, N_("keep the new working tree locked")),
 		OPT__QUIET(&opts.quiet, N_("suppress progress reporting")),
--
2.24.1

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

[SZEDER Gábor]

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?


> Signed-off-by: Pratyush Yadav <me@yadavpratyush.com>
> ---
> For more context:
> https://lore.kernel.org/git/CAPig+cQmqKiYWDWFH5eK2S6XPOi2t2+8Oas8yZa8R=bKLym3wQ@mail.gmail.com/
> 
> I'll send a patch to add the config option as a follow up some time
> later.
> 
>  Documentation/git-worktree.txt | 7 ++++---
>  builtin/worktree.c             | 2 +-
>  2 files changed, 5 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
> index 85d92c9761..cc227dd382 100644
> --- a/Documentation/git-worktree.txt
> +++ b/Documentation/git-worktree.txt
> @@ -9,7 +9,7 @@ git-worktree - Manage multiple working trees
>  SYNOPSIS
>  --------
>  [verse]
> -'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.

While at it, you might want to break this line, as it got too long.

>  'git worktree list' [--porcelain]
>  'git worktree lock' [--reason <string>] <worktree>
>  'git worktree move' <worktree> <new-path>
> @@ -52,7 +52,7 @@ directory specific files such as HEAD, index, etc. `-` may also be
>  specified as `<commit-ish>`; it is synonymous with `@{-1}`.
>  +
>  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.

>  exist a tracking branch in exactly one remote (call it `<remote>`)
>  with a matching name, treat as equivalent to:
>  +
> @@ -69,7 +69,7 @@ branches from there if `<branch>` is ambiguous but exists on the
>  'origin' remote. See also `checkout.defaultRemote` in
>  linkgit:git-config[1].
>  +
> -If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used,
> +If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `-d` used,

Likewise.

>  then, as a convenience, the new worktree is associated with a branch
>  (call it `<branch>`) named after `$(basename <path>)`.  If `<branch>`
>  doesn't exist, a new branch based on HEAD is automatically created as
> @@ -140,6 +140,7 @@ To remove a locked working tree, specify `--force` twice.
>  	exists. `-B` overrides this safeguard, resetting `<new-branch>` to
>  	`<commit-ish>`.
> 
> +-d::
>  --detach::
>  	With `add`, detach HEAD in the new working tree. See "DETACHED HEAD"
>  	in linkgit:git-checkout[1].
> diff --git a/builtin/worktree.c b/builtin/worktree.c
> index d6bc5263f1..dab5f76788 100644
> --- a/builtin/worktree.c
> +++ b/builtin/worktree.c
> @@ -500,7 +500,7 @@ static int add(int ac, const char **av, const char *prefix)
>  			   N_("create a new branch")),
>  		OPT_STRING('B', NULL, &new_branch_force, N_("branch"),
>  			   N_("create or reset a branch")),
> -		OPT_BOOL(0, "detach", &opts.detach, N_("detach HEAD at named commit")),
> +		OPT_BOOL('d', "detach", &opts.detach, N_("detach HEAD at named commit")),
>  		OPT_BOOL(0, "checkout", &opts.checkout, N_("populate the new working tree")),
>  		OPT_BOOL(0, "lock", &opts.keep_locked, N_("keep the new working tree locked")),
>  		OPT__QUIET(&opts.quiet, N_("suppress progress reporting")),
> --
> 2.24.1
> 

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

[Eric Sunshine]

On Mon, Jan 27, 2020 at 7:26 AM SZEDER Gábor <szeder.dev@gmail.com> 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@mail.gmail.com/

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

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

[Eric Sunshine]

On Sat, Jan 25, 2020 at 12:37 PM Pratyush Yadav <me@yadavpratyush.com> wrote:
> [...]
> 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.
>
> Signed-off-by: Pratyush Yadav <me@yadavpratyush.com>
> ---
> For more context:
> https://lore.kernel.org/git/CAPig+cQmqKiYWDWFH5eK2S6XPOi2t2+8Oas8yZa8R=bKLym3wQ@mail.gmail.com/
>
> I'll send a patch to add the config option as a follow up some time
> later.

Although the suggestion of a config option came from me (in [1] and
extended in [2]), I had second thoughts about it very shortly after
sending [2], and can't say that I am particularly in favor of it.
There are at least a couple reasons why I have taken this view.

First, the idea suggested in [2] can be seen as a specialized
mechanism which is perhaps already handled better by the more
generalized mechanism provided by Git aliases. That is, someone can
achieve the same goal of conveniently providing a particular set of
command-line options by simply defining a Git alias; for instance,
"git wttemp" might expand to "git worktree add --detach". We don't
need to be re-inventing the wheel (poorly).

Second, the only real case which has arisen thus far is that of
throwaway (detached) worktrees, and the added '-d' alias for
'--detach' makes that about as simple as possible to achieve without
requiring any extra machinery. If, at some point down the road, other
real-world cases arise in which it would be convenient to tweak
worktree creation in some mechanized fashion, perhaps then it would
make sense to implement all the extra code to support such a config
option, but right now it seems overkill.

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

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

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

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

Yup.  

Even though I do not mind a short-hand '-d', because "worktree add"
would be quite a rare event compared to the use of other Git
subcommands, those who do not remember '--detach' after learning it
would not have any better chance to remember to use the option, even
if a shorter variant '-d' was available.

In other words, if "worktree add --detach" is underused and it is a
problem that needs to be fixed, I do not think the reason why it is
underused is *not* because "--detach" is too long to type or does
not get completed when "git worktree add <TAB>" is typed.  Isn't the
real problem because people do not even *know* that the choice of
starting a worktree without being on a particular branch exists?

A better documentation would help, but I do not think

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

is addressing the right problem.  s/-d/--detach/ may make it more
clear what the option is about, in which case it would be a better
way to promote the feature.