{"thread":{"id":"54186","subject":"[PATCH 0/3] worktree: add -d shorthand for --detach & improve documentation","startedAt":"2020-09-04T07:08:45Z","lastAt":"2020-09-07T00:03:48Z","messageCount":9,"participants":["Eric Sunshine","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"405016","messageId":"20200904070703.47898-1-sunshine@sunshineco.com","threadId":"54186","inReplyTo":null,"subject":"[PATCH 0/3] worktree: add -d shorthand for --detach & improve documentation","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2020-09-04T07:07:00Z","receivedAt":"2020-09-04T07:08:45Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"This series grew directly out of suggestions proposed in [1]. Its\npurpose is twofold. First, it brings git-worktree in line with the other\n\"checkout a branch\" commands git-switch and git-checkout by teaching it\n-d as shorthand for --detach (which those other commands already\nunderstand). Second, it enhances git-worktree documentation to emphasize\nthat `git worktree add ` creates a new branch by default, and to\ndiscuss branch-based vs. throwaway worktrees, which may help newcomers\navoid creating unwanted new branches without realizing they are doing,\nand later wondering why `git branch --list` shows branches they did not\nintentionally create.\n\nThere was an earlier attempt[2] by Pratyush to add -d as shorthand for\n--detach (though it did not enhance git-worktree documentation as the\ncurrent patch series does), however, that patch was never re-rolled\nafter reviewers pushed back on a few of the changes it made.\n\n[1]: https://lore.kernel.org/git/CAPig+cQmqKiYWDWFH5eK2S6XPOi2t2+8Oas8yZa8R=bKLym3wQ@mail.gmail.com/\n[2]: https://lore.kernel.org/git/20200125173744.4334-1-me@yadavpratyush.com/\n\nEric Sunshine (3):\n git-checkout.txt: document -d short option for --detach\n worktree: add -d short option for --detach\n git-worktree.txt: discuss branch-based vs. throwaway worktrees\n\n Documentation/git-checkout.txt | 1 +\n Documentation/git-worktree.txt | 13 +++++++++++++\n builtin/worktree.c | 2 +-\n 3 files changed, 15 insertions(+), 1 deletion(-)\n\n-- \n2.28.0.618.gf4bc123cb7\n\n"},{"id":"405017","messageId":"20200904070703.47898-3-sunshine@sunshineco.com","threadId":"54186","inReplyTo":"20200904070703.47898-1-sunshine@sunshineco.com","subject":"[PATCH 2/3] worktree: add -d short option for --detach","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2020-09-04T07:07:02Z","receivedAt":"2020-09-04T07:08:47Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"Like git-switch and git-checkout, git-worktree can check out a branch or\nset up a detached HEAD. However, unlike git-switch and git-checkout,\ngit-worktree does not understand -d as shorthand for --detach, which may\nconfound users accustomed to using -d for this purpose. Address this\nshortcoming by adding -d as shorthand for --detach in order to bring\ngit-worktree in line with the other commands.\n\nSigned-off-by: Eric Sunshine \n---\n Documentation/git-worktree.txt | 1 +\n builtin/worktree.c | 2 +-\n 2 files changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt\nindex 6ee6ec7982..d252b6873b 100644\n--- a/Documentation/git-worktree.txt\n+++ b/Documentation/git-worktree.txt\n@@ -143,6 +143,7 @@ To remove a locked working tree, specify `--force` twice.\n \texists. `-B` overrides this safeguard, resetting `` to\n \t``.\n \n+-d::\n --detach::\n \tWith `add`, detach `HEAD` in the new working tree. See \"DETACHED HEAD\"\n \tin linkgit:git-checkout[1].\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex 378f332b5d..1737165d2d 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -555,7 +555,7 @@ static int add(int ac, const char **av, const char *prefix)\n \t\t\t N_(\"create a new branch\")),\n \t\tOPT_STRING('B', NULL, &new_branch_force, N_(\"branch\"),\n \t\t\t N_(\"create or reset a branch\")),\n-\t\tOPT_BOOL(0, \"detach\", &opts.detach, N_(\"detach HEAD at named commit\")),\n+\t\tOPT_BOOL('d', \"detach\", &opts.detach, N_(\"detach HEAD at named commit\")),\n \t\tOPT_BOOL(0, \"checkout\", &opts.checkout, N_(\"populate the new working tree\")),\n \t\tOPT_BOOL(0, \"lock\", &opts.keep_locked, N_(\"keep the new working tree locked\")),\n \t\tOPT__QUIET(&opts.quiet, N_(\"suppress progress reporting\")),\n-- \n2.28.0.618.gf4bc123cb7\n\n"},{"id":"405018","messageId":"20200904070703.47898-2-sunshine@sunshineco.com","threadId":"54186","inReplyTo":"20200904070703.47898-1-sunshine@sunshineco.com","subject":"[PATCH 1/3] git-checkout.txt: document -d short option for --detach","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2020-09-04T07:07:01Z","receivedAt":"2020-09-04T07:08:55Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"git-checkout learned -d as short option for --detach in 163e3b2975\n(switch: add short option for --detach, 2019-03-29) but the\ndocumentation was never updated to reflect the change.\n\nSigned-off-by: Eric Sunshine \n---\n Documentation/git-checkout.txt | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 5b697eee1b..afa5c11fd3 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -198,6 +198,7 @@ Use `--no-guess` to disable this.\n \tCreate the new branch's reflog; see linkgit:git-branch[1] for\n \tdetails.\n \n+-d::\n --detach::\n \tRather than checking out a branch to work on it, check out a\n \tcommit for inspection and discardable experiments.\n-- \n2.28.0.618.gf4bc123cb7\n\n"},{"id":"405019","messageId":"20200904070703.47898-4-sunshine@sunshineco.com","threadId":"54186","inReplyTo":"20200904070703.47898-1-sunshine@sunshineco.com","subject":"[PATCH 3/3] git-worktree.txt: discuss branch-based vs. throwaway worktrees","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2020-09-04T07:07:03Z","receivedAt":"2020-09-04T07:08:55Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"By default, \"git worktree add\" creates a new worktree associated with a\nparticular branch (which may have been created automatically if not\nspecified explicitly on the command-line). It is also convenient to\ncreate throwaway worktrees not associated with any branch, which can be\nhandy when making experimental changes or doing testing. However, the\nlatter use-case may not be obvious to newcomers since the high-level\ndescription of worktrees talks only about checking out \"more than one\nbranch at a time\". Therefore, enhance the description to to discuss both\nuse-cases.\n\nA secondary goal of highlighting the distinction between branch-based\nand throwaway worktrees is to help newcomers understand that the\nsimplest form `git worktree add ` automatically creates a new\nbranch. Stating this early in the description, may help newcomers avoid\ncreating unwanted new branches without being aware that they are doing\nso, and later wondering why `git branch --list` shows branches the user\ndid not intentionally create.\n\nSigned-off-by: Eric Sunshine \n---\n Documentation/git-worktree.txt | 12 ++++++++++++\n 1 file changed, 12 insertions(+)\n\ndiff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt\nindex d252b6873b..1449491c1b 100644\n--- a/Documentation/git-worktree.txt\n+++ b/Documentation/git-worktree.txt\n@@ -31,6 +31,18 @@ A repository has one main working tree (if it's not a\n bare repository) and zero or more linked working trees. When you are done\n with a linked working tree, remove it with `git worktree remove`.\n \n+In its simplest form, `git worktree add ` automatically creates a\n+new branch whose name is the final component of ``, which is\n+convenient if you plan to work on a new topic. For instance, `git\n+worktree add ../hotfix` creates new branch `hotfix` and checks it out at\n+path `../hotfix`. To instead work on an existing branch in a new working\n+tree, use `git worktree add `. On the other hand, if you\n+just plan to make some experimental changes or do testing without\n+disturbing existing development, it is often convenient to create a\n+'throwaway' working tree not associated with any branch. For instance,\n+`git worktree add -d ` creates a new working tree with a detached\n+`HEAD` at the same commit as the current branch.\n+\n If a working tree is deleted without using `git worktree remove`, then\n its associated administrative files, which reside in the repository\n (see \"DETAILS\" below), will eventually be removed automatically (see\n-- \n2.28.0.618.gf4bc123cb7\n\n"},{"id":"405104","messageId":"xmqqlfhm36v2.fsf@gitster.c.googlers.com","threadId":"54186","inReplyTo":"20200904070703.47898-1-sunshine@sunshineco.com","subject":"Re: [PATCH 0/3] worktree: add -d shorthand for --detach & improve documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-09-06T21:58:25Z","receivedAt":"2020-09-06T21:58:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n> This series grew directly out of suggestions proposed in [1]. Its\n> purpose is twofold. First, it brings git-worktree in line with the other\n> \"checkout a branch\" commands git-switch and git-checkout by teaching it\n> -d as shorthand for --detach (which those other commands already\n> understand).\n\nHmph, \"checkout\" would not affect list of worktrees, but \"worktree\"\ncould be used to delete an worktree, so I (or any other naive user\nlike me) may mistake \"-d\" to mean \"delete a worktree\".\n\nBut it is not \"teach 'worktree' that -d is shorthand for --detach\";\nit is \"teach 'worktree add' that -d is for --detach\". And in that\ncontext, when adding a new worktree, there is no room for such a\nconfusion to come into the picture.\n\nSo I think it is just the way the series is marketted that triggered\na potential negative reaction from me.\n\n> worktree: add -d short option for --detach\n"},{"id":"405107","messageId":"20200907000222.4717-3-sunshine@sunshineco.com","threadId":"54186","inReplyTo":"20200907000222.4717-1-sunshine@sunshineco.com","subject":"[PATCH v2 2/3] worktree: teach `add` to recognize -d as shorthand for --detach","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2020-09-07T00:02:21Z","receivedAt":"2020-09-07T00:03:39Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"Like `git switch` and `git checkout`, `git worktree add` can check out a\nbranch or set up a detached HEAD. However, unlike those other commands,\n`git worktree add` does not understand -d as shorthand for --detach,\nwhich may confound users accustomed to using -d for this purpose.\nAddress this shortcoming by teaching `add` to recognize -d for --detach,\nthus bringing it in line with the other commands.\n\nSigned-off-by: Eric Sunshine \n---\n Documentation/git-worktree.txt | 1 +\n builtin/worktree.c | 2 +-\n 2 files changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt\nindex 6ee6ec7982..d252b6873b 100644\n--- a/Documentation/git-worktree.txt\n+++ b/Documentation/git-worktree.txt\n@@ -143,6 +143,7 @@ To remove a locked working tree, specify `--force` twice.\n \texists. `-B` overrides this safeguard, resetting `` to\n \t``.\n \n+-d::\n --detach::\n \tWith `add`, detach `HEAD` in the new working tree. See \"DETACHED HEAD\"\n \tin linkgit:git-checkout[1].\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex 378f332b5d..1737165d2d 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -555,7 +555,7 @@ static int add(int ac, const char **av, const char *prefix)\n \t\t\t N_(\"create a new branch\")),\n \t\tOPT_STRING('B', NULL, &new_branch_force, N_(\"branch\"),\n \t\t\t N_(\"create or reset a branch\")),\n-\t\tOPT_BOOL(0, \"detach\", &opts.detach, N_(\"detach HEAD at named commit\")),\n+\t\tOPT_BOOL('d', \"detach\", &opts.detach, N_(\"detach HEAD at named commit\")),\n \t\tOPT_BOOL(0, \"checkout\", &opts.checkout, N_(\"populate the new working tree\")),\n \t\tOPT_BOOL(0, \"lock\", &opts.keep_locked, N_(\"keep the new working tree locked\")),\n \t\tOPT__QUIET(&opts.quiet, N_(\"suppress progress reporting\")),\n-- \n2.28.0.618.gf4bc123cb7\n\n"},{"id":"405108","messageId":"20200907000222.4717-2-sunshine@sunshineco.com","threadId":"54186","inReplyTo":"20200907000222.4717-1-sunshine@sunshineco.com","subject":"[PATCH v2 1/3] git-checkout.txt: document -d short option for --detach","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2020-09-07T00:02:20Z","receivedAt":"2020-09-07T00:03:40Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"`git checkout` learned -d as short option for --detach in 163e3b2975\n(switch: add short option for --detach, 2019-03-29) but the\ndocumentation was never updated to reflect the change.\n\nSigned-off-by: Eric Sunshine \n---\n Documentation/git-checkout.txt | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 5b697eee1b..afa5c11fd3 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -198,6 +198,7 @@ Use `--no-guess` to disable this.\n \tCreate the new branch's reflog; see linkgit:git-branch[1] for\n \tdetails.\n \n+-d::\n --detach::\n \tRather than checking out a branch to work on it, check out a\n \tcommit for inspection and discardable experiments.\n-- \n2.28.0.618.gf4bc123cb7\n\n"},{"id":"405109","messageId":"20200907000222.4717-4-sunshine@sunshineco.com","threadId":"54186","inReplyTo":"20200907000222.4717-1-sunshine@sunshineco.com","subject":"[PATCH v2 3/3] git-worktree.txt: discuss branch-based vs. throwaway worktrees","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2020-09-07T00:02:22Z","receivedAt":"2020-09-07T00:03:40Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"By default, `git worktree add` creates a new worktree associated with a\nparticular branch (which may have been created automatically if not\nspecified explicitly on the command-line). It is also convenient to\ncreate throwaway worktrees not associated with any branch, which can be\nhandy when making experimental changes or doing testing. However, the\nlatter use-case may not be obvious to newcomers since the high-level\ndescription of worktrees talks only about checking out \"more than one\nbranch at a time\". Therefore, enhance the description to to discuss both\nuse-cases.\n\nA secondary goal of highlighting the distinction between branch-based\nand throwaway worktrees is to help newcomers understand that the\nsimplest form `git worktree add ` automatically creates a new\nbranch. Stating this early in the description, may help newcomers avoid\ncreating branches without realizing they are doing so, and later\nwondering why `git branch --list` shows branches the user did not\nintentionally create.\n\nSigned-off-by: Eric Sunshine \n---\n Documentation/git-worktree.txt | 12 ++++++++++++\n 1 file changed, 12 insertions(+)\n\ndiff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt\nindex d252b6873b..1449491c1b 100644\n--- a/Documentation/git-worktree.txt\n+++ b/Documentation/git-worktree.txt\n@@ -31,6 +31,18 @@ A repository has one main working tree (if it's not a\n bare repository) and zero or more linked working trees. When you are done\n with a linked working tree, remove it with `git worktree remove`.\n \n+In its simplest form, `git worktree add ` automatically creates a\n+new branch whose name is the final component of ``, which is\n+convenient if you plan to work on a new topic. For instance, `git\n+worktree add ../hotfix` creates new branch `hotfix` and checks it out at\n+path `../hotfix`. To instead work on an existing branch in a new working\n+tree, use `git worktree add `. On the other hand, if you\n+just plan to make some experimental changes or do testing without\n+disturbing existing development, it is often convenient to create a\n+'throwaway' working tree not associated with any branch. For instance,\n+`git worktree add -d ` creates a new working tree with a detached\n+`HEAD` at the same commit as the current branch.\n+\n If a working tree is deleted without using `git worktree remove`, then\n its associated administrative files, which reside in the repository\n (see \"DETAILS\" below), will eventually be removed automatically (see\n-- \n2.28.0.618.gf4bc123cb7\n\n"},{"id":"405110","messageId":"20200907000222.4717-1-sunshine@sunshineco.com","threadId":"54186","inReplyTo":"20200904070703.47898-1-sunshine@sunshineco.com","subject":"[PATCH v2 0/3] worktree: teach `add` -d for --detach & improve documentation","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2020-09-07T00:02:19Z","receivedAt":"2020-09-07T00:03:48Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"This is a re-roll of [1] which brings `git worktree add` in line with\nthe other \"checkout a branch\" commands `git switch` and `git checkout`\nby teaching it -d as shorthand for --detach (which those other commands\nalready understand). It also enhances `git worktree` documentation to\nemphasize that `git worktree add ` creates a new branch by\ndefault, and to discuss branch-based vs. throwaway worktrees, which may\nhelp newcomers avoid creating branches without realizing they are doing\nso, and later wondering why `git branch --list` shows branches they did\nnot intentionally create.\n\nv2 adjusts the commit message of [2/3] to make it clearer[2] that it\nteaches `git worktree add` (not `git worktree`, in general) to\nrecognized -d as shorthand for --detach.\n\n[1]: https://lore.kernel.org/git/20200904070703.47898-1-sunshine@sunshineco.com/T/\n[2]: https://lore.kernel.org/git/xmqqlfhm36v2.fsf@gitster.c.googlers.com/\n\nEric Sunshine (3):\n git-checkout.txt: document -d short option for --detach\n worktree: teach `add` to recognize -d as shorthand for --detach\n git-worktree.txt: discuss branch-based vs. throwaway worktrees\n\n Documentation/git-checkout.txt | 1 +\n Documentation/git-worktree.txt | 13 +++++++++++++\n builtin/worktree.c | 2 +-\n 3 files changed, 15 insertions(+), 1 deletion(-)\n\nRange-diff against v1:\n1: 61ac1d5e14 ! 1: 538aaaf72d git-checkout.txt: document -d short option for --detach\n @@ Metadata\n ## Commit message ##\n git-checkout.txt: document -d short option for --detach\n \n - git-checkout learned -d as short option for --detach in 163e3b2975\n + `git checkout` learned -d as short option for --detach in 163e3b2975\n (switch: add short option for --detach, 2019-03-29) but the\n documentation was never updated to reflect the change.\n \n2: 4f43ff6ddc ! 2: 49b3b3795d worktree: add -d short option for --detach\n @@ Metadata\n Author: Eric Sunshine \n \n ## Commit message ##\n - worktree: add -d short option for --detach\n + worktree: teach `add` to recognize -d as shorthand for --detach\n \n - Like git-switch and git-checkout, git-worktree can check out a branch or\n - set up a detached HEAD. However, unlike git-switch and git-checkout,\n - git-worktree does not understand -d as shorthand for --detach, which may\n - confound users accustomed to using -d for this purpose. Address this\n - shortcoming by adding -d as shorthand for --detach in order to bring\n - git-worktree in line with the other commands.\n + Like `git switch` and `git checkout`, `git worktree add` can check out a\n + branch or set up a detached HEAD. However, unlike those other commands,\n + `git worktree add` does not understand -d as shorthand for --detach,\n + which may confound users accustomed to using -d for this purpose.\n + Address this shortcoming by teaching `add` to recognize -d for --detach,\n + thus bringing it in line with the other commands.\n \n Signed-off-by: Eric Sunshine \n \n3: 628a7b7bb0 ! 3: e5de1aaf18 git-worktree.txt: discuss branch-based vs. throwaway worktrees\n @@ Metadata\n ## Commit message ##\n git-worktree.txt: discuss branch-based vs. throwaway worktrees\n \n - By default, \"git worktree add\" creates a new worktree associated with a\n + By default, `git worktree add` creates a new worktree associated with a\n particular branch (which may have been created automatically if not\n specified explicitly on the command-line). It is also convenient to\n create throwaway worktrees not associated with any branch, which can be\n @@ Commit message\n and throwaway worktrees is to help newcomers understand that the\n simplest form `git worktree add ` automatically creates a new\n branch. Stating this early in the description, may help newcomers avoid\n - creating unwanted new branches without being aware that they are doing\n - so, and later wondering why `git branch --list` shows branches the user\n - did not intentionally create.\n + creating branches without realizing they are doing so, and later\n + wondering why `git branch --list` shows branches the user did not\n + intentionally create.\n \n Signed-off-by: Eric Sunshine \n \n-- \n2.28.0.618.gf4bc123cb7\n\n"}]}