[PATCH 0/3] worktree: add -d shorthand for --detach & improve documentation

This series grew directly out of suggestions proposed in [1]. Its
purpose is twofold. First, it brings git-worktree in line with the other
"checkout a branch" commands git-switch and git-checkout by teaching it
-d as shorthand for --detach (which those other commands already
understand). Second, it enhances git-worktree documentation to emphasize
that `git worktree add <path>` creates a new branch by default, and to
discuss branch-based vs. throwaway worktrees, which may help newcomers
avoid creating unwanted new branches without realizing they are doing,
and later wondering why `git branch --list` shows branches they did not
intentionally create.

There was an earlier attempt[2] by Pratyush to add -d as shorthand for
--detach (though it did not enhance git-worktree documentation as the
current patch series does), however, that patch was never re-rolled
after reviewers pushed back on a few of the changes it made.

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

Eric Sunshine (3):
  git-checkout.txt: document -d short option for --detach
  worktree: add -d short option for --detach
  git-worktree.txt: discuss branch-based vs. throwaway worktrees

 Documentation/git-checkout.txt |  1 +
 Documentation/git-worktree.txt | 13 +++++++++++++
 builtin/worktree.c             |  2 +-
 3 files changed, 15 insertions(+), 1 deletion(-)

-- 
2.28.0.618.gf4bc123cb7

Like git-switch and git-checkout, git-worktree can check out a branch or
set up a detached HEAD. However, unlike git-switch and git-checkout,
git-worktree does not understand -d as shorthand for --detach, which may
confound users accustomed to using -d for this purpose. Address this
shortcoming by adding -d as shorthand for --detach in order to bring
git-worktree in line with the other commands.

Signed-off-by: Eric Sunshine <redacted>
---
 Documentation/git-worktree.txt | 1 +
 builtin/worktree.c             | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 6ee6ec7982..d252b6873b 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt

@@ -143,6 +143,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 378f332b5d..1737165d2d 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c

@@ -555,7 +555,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.28.0.618.gf4bc123cb7

git-checkout learned -d as short option for --detach in 163e3b2975
(switch: add short option for --detach, 2019-03-29) but the
documentation was never updated to reflect the change.

Signed-off-by: Eric Sunshine <redacted>
---
 Documentation/git-checkout.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 5b697eee1b..afa5c11fd3 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt

@@ -198,6 +198,7 @@ Use `--no-guess` to disable this.
 	Create the new branch's reflog; see linkgit:git-branch[1] for
 	details.
 
+-d::
 --detach::
 	Rather than checking out a branch to work on it, check out a
 	commit for inspection and discardable experiments.

-- 
2.28.0.618.gf4bc123cb7

By default, "git worktree add" creates a new worktree associated with a
particular branch (which may have been created automatically if not
specified explicitly on the command-line). It is also convenient to
create throwaway worktrees not associated with any branch, which can be
handy when making experimental changes or doing testing. However, the
latter use-case may not be obvious to newcomers since the high-level
description of worktrees talks only about checking out "more than one
branch at a time". Therefore, enhance the description to to discuss both
use-cases.

A secondary goal of highlighting the distinction between branch-based
and throwaway worktrees is to help newcomers understand that the
simplest form `git worktree add <path>` automatically creates a new
branch. Stating this early in the description, may help newcomers avoid
creating unwanted new branches without being aware that they are doing
so, and later wondering why `git branch --list` shows branches the user
did not intentionally create.

Signed-off-by: Eric Sunshine <redacted>
---
 Documentation/git-worktree.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index d252b6873b..1449491c1b 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt

@@ -31,6 +31,18 @@ A repository has one main working tree (if it's not a
 bare repository) and zero or more linked working trees. When you are done
 with a linked working tree, remove it with `git worktree remove`.
 
+In its simplest form, `git worktree add <path>` automatically creates a
+new branch whose name is the final component of `<path>`, which is
+convenient if you plan to work on a new topic. For instance, `git
+worktree add ../hotfix` creates new branch `hotfix` and checks it out at
+path `../hotfix`. To instead work on an existing branch in a new working
+tree, use `git worktree add <path> <branch>`. On the other hand, if you
+just plan to make some experimental changes or do testing without
+disturbing existing development, it is often convenient to create a
+'throwaway' working tree not associated with any branch. For instance,
+`git worktree add -d <path>` creates a new working tree with a detached
+`HEAD` at the same commit as the current branch.
+
 If a working tree is deleted without using `git worktree remove`, then
 its associated administrative files, which reside in the repository
 (see "DETAILS" below), will eventually be removed automatically (see

-- 
2.28.0.618.gf4bc123cb7

Eric Sunshine [off-list ref] writes:

This series grew directly out of suggestions proposed in [1]. Its
purpose is twofold. First, it brings git-worktree in line with the other
"checkout a branch" commands git-switch and git-checkout by teaching it
-d as shorthand for --detach (which those other commands already
understand).

Hmph, "checkout" would not affect list of worktrees, but "worktree"
could be used to delete an worktree, so I (or any other naive user
like me) may mistake "-d" to mean "delete a worktree".

But it is not "teach 'worktree' that -d is shorthand for --detach";
it is "teach 'worktree add' that -d is for --detach".  And in that
context, when adding a new worktree, there is no room for such a
confusion to come into the picture.

So I think it is just the way the series is marketted that triggered
a potential negative reaction from me.

  worktree: add -d short option for --detach

Like `git switch` and `git checkout`, `git worktree add` can check out a
branch or set up a detached HEAD. However, unlike those other commands,
`git worktree add` does not understand -d as shorthand for --detach,
which may confound users accustomed to using -d for this purpose.
Address this shortcoming by teaching `add` to recognize -d for --detach,
thus bringing it in line with the other commands.

Signed-off-by: Eric Sunshine <redacted>
---
 Documentation/git-worktree.txt | 1 +
 builtin/worktree.c             | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 6ee6ec7982..d252b6873b 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt

@@ -143,6 +143,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 378f332b5d..1737165d2d 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c

@@ -555,7 +555,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.28.0.618.gf4bc123cb7

`git checkout` learned -d as short option for --detach in 163e3b2975
(switch: add short option for --detach, 2019-03-29) but the
documentation was never updated to reflect the change.

Signed-off-by: Eric Sunshine <redacted>
---
 Documentation/git-checkout.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 5b697eee1b..afa5c11fd3 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt

@@ -198,6 +198,7 @@ Use `--no-guess` to disable this.
 	Create the new branch's reflog; see linkgit:git-branch[1] for
 	details.
 
+-d::
 --detach::
 	Rather than checking out a branch to work on it, check out a
 	commit for inspection and discardable experiments.

-- 
2.28.0.618.gf4bc123cb7

By default, `git worktree add` creates a new worktree associated with a
particular branch (which may have been created automatically if not
specified explicitly on the command-line). It is also convenient to
create throwaway worktrees not associated with any branch, which can be
handy when making experimental changes or doing testing. However, the
latter use-case may not be obvious to newcomers since the high-level
description of worktrees talks only about checking out "more than one
branch at a time". Therefore, enhance the description to to discuss both
use-cases.

A secondary goal of highlighting the distinction between branch-based
and throwaway worktrees is to help newcomers understand that the
simplest form `git worktree add <path>` automatically creates a new
branch. Stating this early in the description, may help newcomers avoid
creating branches without realizing they are doing so, and later
wondering why `git branch --list` shows branches the user did not
intentionally create.

Signed-off-by: Eric Sunshine <redacted>
---
 Documentation/git-worktree.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index d252b6873b..1449491c1b 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt

@@ -31,6 +31,18 @@ A repository has one main working tree (if it's not a
 bare repository) and zero or more linked working trees. When you are done
 with a linked working tree, remove it with `git worktree remove`.
 
+In its simplest form, `git worktree add <path>` automatically creates a
+new branch whose name is the final component of `<path>`, which is
+convenient if you plan to work on a new topic. For instance, `git
+worktree add ../hotfix` creates new branch `hotfix` and checks it out at
+path `../hotfix`. To instead work on an existing branch in a new working
+tree, use `git worktree add <path> <branch>`. On the other hand, if you
+just plan to make some experimental changes or do testing without
+disturbing existing development, it is often convenient to create a
+'throwaway' working tree not associated with any branch. For instance,
+`git worktree add -d <path>` creates a new working tree with a detached
+`HEAD` at the same commit as the current branch.
+
 If a working tree is deleted without using `git worktree remove`, then
 its associated administrative files, which reside in the repository
 (see "DETAILS" below), will eventually be removed automatically (see

-- 
2.28.0.618.gf4bc123cb7

This is a re-roll of [1] which brings `git worktree add` in line with
the other "checkout a branch" commands `git switch` and `git checkout`
by teaching it -d as shorthand for --detach (which those other commands
already understand). It also enhances `git worktree` documentation to
emphasize that `git worktree add <path>` creates a new branch by
default, and to discuss branch-based vs. throwaway worktrees, which may
help newcomers avoid creating branches without realizing they are doing
so, and later wondering why `git branch --list` shows branches they did
not intentionally create.

v2 adjusts the commit message of [2/3] to make it clearer[2] that it
teaches `git worktree add` (not `git worktree`, in general) to
recognized -d as shorthand for --detach.

[1]: https://lore.kernel.org/git/20200904070703.47898-1-sunshine@sunshineco.com/T/
[2]: https://lore.kernel.org/git/xmqqlfhm36v2.fsf@gitster.c.googlers.com/

Eric Sunshine (3):
  git-checkout.txt: document -d short option for --detach
  worktree: teach `add` to recognize -d as shorthand for --detach
  git-worktree.txt: discuss branch-based vs. throwaway worktrees

 Documentation/git-checkout.txt |  1 +
 Documentation/git-worktree.txt | 13 +++++++++++++
 builtin/worktree.c             |  2 +-
 3 files changed, 15 insertions(+), 1 deletion(-)

Range-diff against v1:
1:  61ac1d5e14 ! 1:  538aaaf72d git-checkout.txt: document -d short option for --detach
    @@ Metadata
      ## Commit message ##
         git-checkout.txt: document -d short option for --detach
     
    -    git-checkout learned -d as short option for --detach in 163e3b2975
    +    `git checkout` learned -d as short option for --detach in 163e3b2975
         (switch: add short option for --detach, 2019-03-29) but the
         documentation was never updated to reflect the change.
     
2:  4f43ff6ddc ! 2:  49b3b3795d worktree: add -d short option for --detach
    @@ Metadata
     Author: Eric Sunshine [off-list ref]
     
      ## Commit message ##
    -    worktree: add -d short option for --detach
    +    worktree: teach `add` to recognize -d as shorthand for --detach
     
    -    Like git-switch and git-checkout, git-worktree can check out a branch or
    -    set up a detached HEAD. However, unlike git-switch and git-checkout,
    -    git-worktree does not understand -d as shorthand for --detach, which may
    -    confound users accustomed to using -d for this purpose. Address this
    -    shortcoming by adding -d as shorthand for --detach in order to bring
    -    git-worktree in line with the other commands.
    +    Like `git switch` and `git checkout`, `git worktree add` can check out a
    +    branch or set up a detached HEAD. However, unlike those other commands,
    +    `git worktree add` does not understand -d as shorthand for --detach,
    +    which may confound users accustomed to using -d for this purpose.
    +    Address this shortcoming by teaching `add` to recognize -d for --detach,
    +    thus bringing it in line with the other commands.
     
         Signed-off-by: Eric Sunshine [off-list ref]
     
3:  628a7b7bb0 ! 3:  e5de1aaf18 git-worktree.txt: discuss branch-based vs. throwaway worktrees
    @@ Metadata
      ## Commit message ##
         git-worktree.txt: discuss branch-based vs. throwaway worktrees
     
    -    By default, "git worktree add" creates a new worktree associated with a
    +    By default, `git worktree add` creates a new worktree associated with a
         particular branch (which may have been created automatically if not
         specified explicitly on the command-line). It is also convenient to
         create throwaway worktrees not associated with any branch, which can be
    @@ Commit message
         and throwaway worktrees is to help newcomers understand that the
         simplest form `git worktree add <path>` automatically creates a new
         branch. Stating this early in the description, may help newcomers avoid
    -    creating unwanted new branches without being aware that they are doing
    -    so, and later wondering why `git branch --list` shows branches the user
    -    did not intentionally create.
    +    creating branches without realizing they are doing so, and later
    +    wondering why `git branch --list` shows branches the user did not
    +    intentionally create.
     
         Signed-off-by: Eric Sunshine [off-list ref]
     
-- 
2.28.0.618.gf4bc123cb7