git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v6 0/4] worktree: Support `--orphan` when creating new worktrees

From
Jacob Abel <jacobabel@nullpo.dev>
Date
Dec 28, 2022, 06:16 UTC
Message-ID
<20221228061539.13740-1-jacobabel@nullpo.dev>
In-Reply-To
<20221220023637.29042-1-jacobabel@nullpo.dev>

While working with the worktree based git workflow, I realised that setting up a new git repository required switching between the traditional and worktree based workflows. Searching online I found a SO answer [1] which seemed to support this and which indicated that adding support for this should not be technically difficult.

This patchset has four parts:
  * adding `-B` to the usage docs (noticed during dev and it seemed too small
    to justify a separate submission)
  * adding a helper fn to simplify testing for mutual exclusion of options
    in `t/t2400-worktree-add.sh`
  * adding orphan branch functionality (as is present in `git-switch`)
    to `git-worktree-add`
  * adding an advise for using --orphan when `git worktree add` fails due to
    a bad ref.
Changes from v5:
  * Touched up commit title and message for 1/4 [2].
  * Changed `[-b | -B]` to `(-b | -B)` in 1/4 [2].
  * Add whitespace to both sides of () for test_wt_add_excl() in t2400 (2/4) [3].
  * Changed test_wt_add_excl() to use `$*` and `$@` instead of `$opts` (2/4) [3].
  * Added save_param_arr() to preserve "$@" from being reset by
    test_expect_success() in test_wt_add_excl() (2/4).
  * Reordered Signed-off-by lines in 3/4 [4].
  * Cleaned up commit message in 3/4 to better illustrate the change [4].
  * Cleaned up commit message in 4/4 to better illustrate the change.
  * Cleaned up commit title in 4/4 [5].
  * Changed test_wt_add_empty_repo_orphan_hint() to use `$@` instead
    of `$opts` (4/4) [5].
1. https://stackoverflow.com/a/68717229/15064705/
2. https://lore.kernel.org/git/xmqqo7ryyc4f.fsf@gitster.g/
3. https://lore.kernel.org/git/xmqqsfhawwqf.fsf@gitster.g/
4. https://lore.kernel.org/git/xmqqlen2wvtn.fsf@gitster.g/
5. https://lore.kernel.org/git/xmqqfsdawqbw.fsf@gitster.g/
Jacob Abel (4):
  worktree add: include -B in usage docs
  worktree add: refactor opt exclusion tests
  worktree add: add --orphan flag
  worktree add: add hint to direct users towards --orphan
 Documentation/config/advice.txt |   4 ++
 Documentation/git-worktree.txt  |  17 ++++-
 advice.c                        |   1 +
 advice.h                        |   1 +
 builtin/worktree.c              |  65 +++++++++++++++++--
 t/t2400-worktree-add.sh         | 110 +++++++++++++++++++++++++++++---
 6 files changed, 181 insertions(+), 17 deletions(-)
Range-diff against v5:
1:  05371640ad ! 1:  a9ef3eca7b worktree add: Include -B in usage docs
    @@ Metadata
     Author: Jacob Abel <jacobabel@nullpo.dev>
      ## Commit message ##
    -    worktree add: Include -B in usage docs
    +    worktree add: include -B in usage docs
    -    While -B behavior is already documented, it was not included in the
    -    usage docs for either the man page or the help text. This change fixes
    -    that and brings the usage docs in line with how the flags are documented
    -    in other commands such as git checkout.
    +    Document `-B` next to where `-b` is already documented to bring the
    +    usage docs in line with other commands such as git checkout.
         Signed-off-by: Jacob Abel <jacobabel@nullpo.dev>
    @@ Documentation/git-worktree.txt: SYNOPSIS
      [verse]
      'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]]
     -		   [-b <new-branch>] <path> [<commit-ish>]
    -+		   [[-b | -B] <new-branch>] <path> [<commit-ish>]
    ++		   [(-b | -B) <new-branch>] <path> [<commit-ish>]
      'git worktree list' [-v | --porcelain [-z]]
      'git worktree lock' [--reason <string>] <worktree>
      'git worktree move' <worktree> <new-path>
    @@ builtin/worktree.c
      #define BUILTIN_WORKTREE_ADD_USAGE \
      	N_("git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]\n" \
     -	   "                 [-b <new-branch>] <path> [<commit-ish>]")
    -+	   "                 [[-b | -B] <new-branch>] <path> [<commit-ish>]")
    ++	   "                 [(-b | -B) <new-branch>] <path> [<commit-ish>]")
      #define BUILTIN_WORKTREE_LIST_USAGE \
      	N_("git worktree list [-v | --porcelain [-z]]")
      #define BUILTIN_WORKTREE_LOCK_USAGE \
2:  3d8b26f9d6 ! 2:  c03c112f79 worktree add: refactor opt exclusion tests
    @@ t/t2400-worktree-add.sh: test_expect_success '"add" no auto-vivify with --detach
     -test_expect_success '"add" -b/-B mutually exclusive' '
     -	test_must_fail git worktree add -b poodle -B poodle bamboo main
     -'
    --
    ++# Saves parameter sequence/array as a string so they can be safely stored in a
    ++# variable and restored with `eval "set -- $arr"`. Sourced from
    ++# https://stackoverflow.com/a/27503158/15064705
    ++save_param_arr () {
    ++	local i
    ++	for i;
    ++	do
    ++		# For each argument:
    ++		# 1. Append "\n" after each entry
    ++		# 2. Convert "'" into "'\''"
    ++		# 3. Prepend "'" before each entry
    ++		# 4. Append " \" after each entry
    ++		printf "%s\\n" "$i" | sed "
    ++			s/'/'\\\\''/g
    ++			1s/^/'/
    ++			\$s/\$/' \\\\/
    ++		"
    ++	done
    ++	echo " "
    ++}
    +
     -test_expect_success '"add" -b/--detach mutually exclusive' '
     -	test_must_fail git worktree add -b poodle --detach bamboo main
     -'
     +# Helper function to test mutually exclusive options.
    -+test_wt_add_excl() {
    -+	local opts="$@" &&
    -+	test_expect_success "'worktree add' with '$opts' has mutually exclusive options" '
    -+		test_must_fail git worktree add $opts
    ++test_wt_add_excl () {
    ++	local arr=$(save_param_arr "$@")
    ++	test_expect_success "'worktree add' with $* has mutually exclusive options" '
    ++		eval "set -- $arr" &&
    ++		test_must_fail git worktree add "$@"
     +	'
     +}
3:  ccae9cec2e ! 3:  9b93e2493a worktree add: add --orphan flag
    @@ Commit message
         workflow.
         Current Behavior:
    -
    -    % git init --bare foo.git
    -    Initialized empty Git repository in /path/to/foo.git/
    +    % git -C foo.git --no-pager branch -l
    +    + main
         % git -C foo.git worktree add main/
         Preparing worktree (new branch 'main')
    +    HEAD is now at 6c93a75 a commit
    +    %
    +
    +    % git init bar.git
    +    Initialized empty Git repository in /path/to/bar.git/
    +    % git -C bar.git --no-pager branch -l
    +
    +    % git -C bar.git worktree add main/
    +    Preparing worktree (new branch 'main')
         fatal: not a valid object name: 'HEAD'
         %
         New Behavior:
    -    % git init --bare foo.git
    -    Initialized empty Git repository in /path/to/foo.git/
    -    % git -C foo.git worktree add --orphan main main/
    +    % git -C foo.git --no-pager branch -l
    +    + main
    +    % git -C foo.git worktree add main/
    +    Preparing worktree (new branch 'main')
    +    HEAD is now at 6c93a75 a commit
    +    %
    +
    +    % git init --bare bar.git
    +    Initialized empty Git repository in /path/to/bar.git/
    +    % git -C bar.git --no-pager branch -l
    +
    +    % git -C bar.git worktree add main/
    +    Preparing worktree (new branch 'main')
    +    fatal: invalid reference: HEAD
    +    % git -C bar.git worktree add --orphan main main/
         Preparing worktree (new branch 'main')
         %
    -    Signed-off-by: Jacob Abel <jacobabel@nullpo.dev>
         Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
    +    Signed-off-by: Jacob Abel <jacobabel@nullpo.dev>
      ## Documentation/git-worktree.txt ##
     @@ Documentation/git-worktree.txt: SYNOPSIS
      [verse]
      'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]]
    - 		   [[-b | -B] <new-branch>] <path> [<commit-ish>]
    + 		   [(-b | -B) <new-branch>] <path> [<commit-ish>]
     +'git worktree add' [-f] [--lock [--reason <string>]]
     +		   --orphan <new-branch> <path>
      'git worktree list' [-v | --porcelain [-z]]
    @@ builtin/worktree.c
      #define BUILTIN_WORKTREE_ADD_USAGE \
      	N_("git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]\n" \
    --	   "                 [[-b | -B] <new-branch>] <path> [<commit-ish>]")
    -+	   "                 [[-b | -B] <new-branch>] <path> [<commit-ish>]"), \
    +-	   "                 [(-b | -B) <new-branch>] <path> [<commit-ish>]")
    ++	   "                 [(-b | -B) <new-branch>] <path> [<commit-ish>]"), \
     +	N_("git worktree add [-f] [--lock [--reason <string>]]\n" \
     +	   "                 --orphan <new-branch> <path>")
     +
    @@ builtin/worktree.c: static int add(int ac, const char **av, const char *prefix)
      		strvec_push(&cp.args, "branch");
      ## t/t2400-worktree-add.sh ##
    -@@ t/t2400-worktree-add.sh: test_wt_add_excl() {
    +@@ t/t2400-worktree-add.sh: test_wt_add_excl () {
      test_wt_add_excl -b poodle -B poodle bamboo main
      test_wt_add_excl -b poodle --detach bamboo main
      test_wt_add_excl -B poodle --detach bamboo main
4:  df4c1fa469 ! 4:  737fca6986 worktree add: Add hint to use --orphan when bad ref
    @@ Metadata
     Author: Jacob Abel <jacobabel@nullpo.dev>
      ## Commit message ##
    -    worktree add: Add hint to use --orphan when bad ref
    +    worktree add: add hint to direct users towards --orphan
         Adds a new advice/hint in `git worktree add` for when the user
         tries to create a new worktree from a reference that doesn't exist.
    +    Current Behavior:
    +
    +    % git init --bare foo.git
    +    Initialized empty Git repository in /path/to/foo.git/
    +    % git -C foo.git worktree add main/
    +    Preparing worktree (new branch 'main')
    +    fatal: invalid reference: HEAD
    +    %
    +
    +    New Behavior:
    +
    +    % git init --bare foo.git
    +    Initialized empty Git repository in /path/to/foo.git/
    +    % git -C foo.git worktree add main/
    +    Preparing worktree (new branch 'main')
    +    hint: If you meant to create a worktree containing a new orphan branch
    +    hint: (branch with no commits) for this repository, you can do so
    +    hint: using the --orphan option:
    +    hint:
    +    hint:   git worktree add --orphan main ./main
    +    hint:
    +    hint: Disable this message with "git config advice.worktreeAddOrphan false"
    +    fatal: invalid reference: HEAD
    +    %
    +
         Signed-off-by: Jacob Abel <jacobabel@nullpo.dev>
      ## Documentation/config/advice.txt ##
    @@ t/t2400-worktree-add.sh: test_expect_success '"add" worktree with orphan branch,
      	test_cmp expect .git/worktrees/orphan-with-lock-reason/locked
      '
    -+test_wt_add_empty_repo_orphan_hint() {
    ++test_wt_add_empty_repo_orphan_hint () {
     +	local context="$1"
     +	shift
    -+	local opts="$@"
    ++	local arr=$(save_param_arr "$@")
     +	test_expect_success "'worktree add' show orphan hint in empty repo w/ $context" '
    ++		eval "set -- $arr" &&
     +		test_when_finished "rm -rf empty_repo" &&
     +		GIT_DIR="empty_repo" git init --bare &&
    -+		test_must_fail git -C empty_repo worktree add $opts foobar/ 2> actual &&
    ++		test_must_fail git -C empty_repo worktree add "$@" foobar/ 2> actual &&
     +		grep "hint: If you meant to create a worktree containing a new orphan branch" actual
     +	'
     +}
--
2.38.2
Previous: Jacob AbelNext: Jacob Abel
Message 81 of 129 in “worktree: Support `--orphan` when creating new worktrees”
  1. 0/4 worktree: Support `--orphan` when creating new worktreesJacob Abel, Nov 4, 2022
  2. 1/4 worktree add: Include -B in usage docsJacob Abel, Nov 4, 2022
  3. Eric SunshineNov 4, 2022
  4. Jacob AbelNov 4, 2022
  5. 2/4 builtin/worktree.c: Update checkout_worktree() to use git-worktreeJacob Abel, Nov 4, 2022
  6. Ævar Arnfjörð BjarmasonNov 4, 2022
  7. Jacob AbelNov 4, 2022
  8. Taylor BlauNov 4, 2022
  9. 3/4 worktree add: add --orphan flagJacob Abel, Nov 4, 2022
  10. Ævar Arnfjörð BjarmasonNov 4, 2022
  11. Jacob AbelNov 4, 2022
  12. Eric SunshineNov 4, 2022
  13. Jacob AbelNov 4, 2022
  14. Eric SunshineNov 10, 2022
  15. Jacob AbelNov 10, 2022
  16. 4/4 worktree add: Add unit tests for --orphanJacob Abel, Nov 4, 2022
  17. Ævar Arnfjörð BjarmasonNov 4, 2022
  18. Jacob AbelNov 4, 2022
  19. Eric SunshineNov 4, 2022
  20. Jacob AbelNov 4, 2022
  21. Jacob AbelNov 4, 2022
  22. 0/2 worktree: Support `--orphan` when creating new worktreesJacob Abel, Nov 4, 2022
  23. 1/2 worktree add: Include -B in usage docsJacob Abel, Nov 4, 2022
  24. 2/2 worktree add: add --orphan flagJacob Abel, Nov 4, 2022
  25. 0/2 worktree: Support `--orphan` when creating new worktreesJacob Abel, Nov 10, 2022
  26. 1/2 worktree add: Include -B in usage docsJacob Abel, Nov 10, 2022
  27. 2/2 worktree add: add --orphan flagJacob Abel, Nov 10, 2022
  28. Ævar Arnfjörð BjarmasonNov 15, 2022
  29. Eric SunshineNov 15, 2022
  30. Ævar Arnfjörð BjarmasonNov 15, 2022
  31. Eric SunshineNov 16, 2022
  32. Jacob AbelNov 19, 2022
  33. Jacob AbelNov 19, 2022
  34. Ævar Arnfjörð BjarmasonNov 19, 2022
  35. Jacob AbelNov 19, 2022
  36. Eric SunshineNov 22, 2022
  37. Jacob AbelNov 22, 2022
  38. Ævar Arnfjörð BjarmasonNov 15, 2022
  39. Jacob AbelNov 19, 2022
  40. Ævar Arnfjörð BjarmasonNov 19, 2022
  41. Eric SunshineNov 16, 2022
  42. Ævar Arnfjörð BjarmasonNov 17, 2022
  43. Jacob AbelNov 19, 2022
  44. Ævar Arnfjörð BjarmasonNov 19, 2022
  45. Eric SunshineNov 22, 2022
  46. Jacob AbelNov 22, 2022
  47. Ævar Arnfjörð BjarmasonNov 22, 2022
  48. Jacob AbelNov 23, 2022
  49. Rubén JustoNov 23, 2022
  50. Jacob AbelNov 23, 2022
  51. Rubén JustoNov 23, 2022
  52. Phillip WoodNov 22, 2022
  53. Jacob AbelNov 23, 2022
  54. 0/3 worktree: Support `--orphan` when creating new worktreesJacob Abel, Dec 12, 2022
  55. 1/3 worktree add: Include -B in usage docsJacob Abel, Dec 12, 2022
  56. 2/3 worktree add: add --orphan flagJacob Abel, Dec 12, 2022
  57. Ævar Arnfjörð BjarmasonDec 12, 2022
  58. Jacob AbelDec 12, 2022
  59. Ævar Arnfjörð BjarmasonDec 12, 2022
  60. Jacob AbelDec 12, 2022
  61. 3/3 worktree add: Add hint to use --orphan when bad refJacob Abel, Dec 12, 2022
  62. Ævar Arnfjörð BjarmasonDec 12, 2022
  63. Jacob AbelDec 12, 2022
  64. Ævar Arnfjörð BjarmasonDec 12, 2022
  65. Eric SunshineDec 12, 2022
  66. Jacob AbelDec 12, 2022
  67. Jacob AbelDec 12, 2022
  68. 0/4 worktree: Support `--orphan` when creating new worktreesJacob Abel, Dec 20, 2022
  69. 1/4 worktree add: Include -B in usage docsJacob Abel, Dec 20, 2022
  70. Junio C HamanoDec 20, 2022
  71. Jacob AbelDec 20, 2022
  72. 2/4 worktree add: refactor opt exclusion testsJacob Abel, Dec 20, 2022
  73. Junio C HamanoDec 20, 2022
  74. Jacob AbelDec 20, 2022
  75. 3/4 worktree add: add --orphan flagJacob Abel, Dec 20, 2022
  76. Junio C HamanoDec 20, 2022
  77. Jacob AbelDec 21, 2022
  78. 4/4 worktree add: Add hint to use --orphan when bad refJacob Abel, Dec 20, 2022
  79. Junio C HamanoDec 20, 2022
  80. Jacob AbelDec 21, 2022
  81. 0/4 worktree: Support `--orphan` when creating new worktreesJacob Abel, Dec 28, 2022
  82. 1/4 worktree add: include -B in usage docsJacob Abel, Dec 28, 2022
  83. 2/4 worktree add: refactor opt exclusion testsJacob Abel, Dec 28, 2022
  84. Junio C HamanoDec 28, 2022
  85. Jacob AbelDec 29, 2022
  86. Junio C HamanoDec 29, 2022
  87. Jacob AbelDec 29, 2022
  88. Jacob AbelJan 6, 2023
  89. Junio C HamanoJan 6, 2023
  90. Jacob AbelJan 7, 2023
  91. 3/4 worktree add: add --orphan flagJacob Abel, Dec 28, 2022
  92. 4/4 worktree add: add hint to direct users towards --orphanJacob Abel, Dec 28, 2022
  93. Phillip WoodJan 6, 2023
  94. Ævar Arnfjörð BjarmasonDec 28, 2022
  95. Jacob AbelDec 29, 2022
  96. Ævar Arnfjörð BjarmasonDec 29, 2022
  97. Jacob AbelDec 29, 2022
  98. 0/4 worktree: Support `--orphan` when creating new worktreesJacob Abel, Jan 7, 2023
  99. 1/4 worktree add: include -B in usage docsJacob Abel, Jan 7, 2023
  100. 2/4 worktree add: refactor opt exclusion testsJacob Abel, Jan 7, 2023
  101. Junio C HamanoJan 8, 2023
  102. Jacob AbelJan 8, 2023
  103. 3/4 worktree add: add --orphan flagJacob Abel, Jan 7, 2023
  104. 4/4 worktree add: add hint to direct users towards --orphanJacob Abel, Jan 7, 2023
  105. Ævar Arnfjörð BjarmasonJan 9, 2023
  106. Jacob AbelJan 9, 2023
  107. Ævar Arnfjörð BjarmasonJan 9, 2023
  108. Jacob AbelJan 9, 2023
  109. 0/4 worktree: Support `--orphan` when creating new worktreesJacob Abel, Jan 9, 2023
  110. 1/4 worktree add: include -B in usage docsJacob Abel, Jan 9, 2023
  111. 3/4 worktree add: add --orphan flagJacob Abel, Jan 9, 2023
  112. Phillip WoodJan 13, 2023
  113. Junio C HamanoJan 13, 2023
  114. Jacob AbelJan 14, 2023
  115. Junio C HamanoJan 15, 2023
  116. rsbecker@nexbridge.comJan 15, 2023
  117. Junio C HamanoJan 15, 2023
  118. 'Jacob Abel'Jan 18, 2023
  119. Jacob AbelJan 18, 2023
  120. Ævar Arnfjörð BjarmasonJan 19, 2023
  121. Junio C HamanoJan 19, 2023
  122. Phillip WoodJan 16, 2023
  123. Jacob AbelJan 18, 2023
  124. Phillip WoodJan 19, 2023
  125. Jacob AbelJan 19, 2023
  126. 2/4 worktree add: refactor opt exclusion testsJacob Abel, Jan 9, 2023
  127. 4/4 worktree add: add hint to direct users towards --orphanJacob Abel, Jan 9, 2023
  128. Ævar Arnfjörð BjarmasonJan 9, 2023
  129. Junio C HamanoJan 13, 2023

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.