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

[Jacob Abel <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 v4:

  * Removed redundant var `ret` from `make_worktree_orphan()` [2].
  * Separate vars and decls in `make_worktree_orphan()` [2].
  * Remove accidental `if () {}` diff-noise [2].
  * Remove redundant comment regarding `new_branch_force` [2].
  * Remove redundant comment when `branch` is a bad ref [2].
  * Simplify mutual-exclusion-of-opts testing in t2400 w/
    `test_wt_add_empty_repo_orphan_hint()` helper fn [2].
  * Remove duplicate `-B --detach` exclusion test [3].
  * Remove redundant comment in `test_wt_add_empty_repo_orphan_hint()`
    in t2400 [4].
  * Move test path into `test_wt_add_empty_repo_orphan_hint()` to simplify
    commands [4].
  * Replace added bash-ism with shell syntax [4].
  * Remove confusing `e.g. %s` from advise [4].
  * Reflow advise text [5].
  * Add translation macro `_()` to advise text [5].

1. https://stackoverflow.com/a/68717229/15064705/
2. https://lore.kernel.org/git/221212.86tu2158bz.gmgdl@evledraar.gmail.com/
3. https://lore.kernel.org/git/20221212145515.pohzoyllo3bgz7eb@phi/
4. https://lore.kernel.org/git/221212.86pmcp57w4.gmgdl@evledraar.gmail.com/
5. https://lore.kernel.org/git/221212.86zgbs4h9f.gmgdl@evledraar.gmail.com/

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 use --orphan when bad ref

 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         | 89 +++++++++++++++++++++++++++++----
 6 files changed, 159 insertions(+), 18 deletions(-)

Range-diff against v4:
1:  f35d78cfb4 = 1:  05371640ad worktree add: Include -B in usage docs
-:  ---------- > 2:  3d8b26f9d6 worktree add: refactor opt exclusion tests
2:  8b1cdf1322 ! 3:  ccae9cec2e worktree add: add --orphan flag
    @@ builtin/worktree.c: static int checkout_worktree(const struct add_opts *opts,
     +static int make_worktree_orphan(const char * ref, const struct add_opts *opts,
     +				struct strvec *child_env)
     +{
    -+	int ret;
     +	struct strbuf symref = STRBUF_INIT;
     +	struct child_process cp = CHILD_PROCESS_INIT;
    -+	cp.git_cmd = 1;
     +
     +	validate_new_branchname(ref, &symref, 0);
     +	strvec_pushl(&cp.args, "symbolic-ref", "HEAD", symref.buf, NULL);
     +	if (opts->quiet)
     +		strvec_push(&cp.args, "--quiet");
     +	strvec_pushv(&cp.env, child_env->v);
    -+	ret = run_command(&cp);
     +	strbuf_release(&symref);
    -+	return ret;
    ++	cp.git_cmd = 1;
    ++	return run_command(&cp);
     +}
     +
      static int add_worktree(const char *path, const char *refname,
    @@ builtin/worktree.c: static int add_worktree(const char *path, const char *refnam
      	}
      	commit = lookup_commit_reference_by_name(refname);
     -	if (!commit)
    -+	if (!commit && !opts->orphan) {
    ++	if (!commit && !opts->orphan)
      		die(_("invalid reference: %s"), refname);
    -+	}

      	name = worktree_basename(path, &len);
    - 	strbuf_add(&sb, name, path + len - name);
     @@ builtin/worktree.c: static int add_worktree(const char *path, const char *refname,
      	strvec_pushf(&child_env, "%s=%s", GIT_WORK_TREE_ENVIRONMENT, path);
      	cp.git_cmd = 1;
    @@ builtin/worktree.c: static int add(int ac, const char **av, const char *prefix)
      	if (lock_reason && !keep_locked)
      		die(_("the option '%s' requires '%s'"), "--reason", "--lock");
      	if (lock_reason)
    -@@ builtin/worktree.c: static int add(int ac, const char **av, const char *prefix)
    - 	if (!strcmp(branch, "-"))
    - 		branch = "@{-1}";
    -
    -+	/*
    -+	 * When creating a new branch, new_branch now contains the branch to
    -+	 * create.
    -+	 *
    -+	 * Past this point, new_branch_force can be treated solely as a
    -+	 * boolean flag to indicate whether `-B` was selected.
    -+	 */
    - 	if (new_branch_force) {
    - 		struct strbuf symref = STRBUF_INIT;
    -
     @@ builtin/worktree.c: static int add(int ac, const char **av, const char *prefix)
      		strbuf_release(&symref);
      	}
    @@ builtin/worktree.c: static int add(int ac, const char **av, const char *prefix)
     +	if (opts.orphan) {
     +		branch = new_branch;
     +	} else if (!lookup_commit_reference_by_name(branch)) {
    -+		/*
    -+		 * If `branch` does not reference a valid commit, a new
    -+		 * worktree (and/or branch) cannot be created based off of it.
    -+		 */
     +		die(_("invalid reference: %s"), branch);
     +	} else if (new_branch) {
      		struct child_process cp = CHILD_PROCESS_INIT;
    @@ 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_expect_success '"add" no auto-vivify with --detach and <branch> omitted' '
    - 	test_must_fail git -C mish/mash symbolic-ref HEAD
    - '
    -
    --test_expect_success '"add" -b/-B mutually exclusive' '
    --	test_must_fail git worktree add -b poodle -B poodle bamboo main
    --'
    --
    --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_expect_success '"add" -B/--detach mutually exclusive' '
    --	test_must_fail git worktree add -B poodle --detach bamboo main
    --'
    -+test_wt_add_excl -b poodle -B poodle bamboo main
    -+test_wt_add_excl -b poodle --orphan poodle bamboo
    -+test_wt_add_excl -b poodle --detach bamboo main
    -+test_wt_add_excl -B poodle --detach bamboo main
    -+test_wt_add_excl -B poodle --detach bamboo main
    +@@ 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
     +test_wt_add_excl -B poodle --orphan poodle bamboo
    ++test_wt_add_excl -b poodle --orphan poodle bamboo
     +test_wt_add_excl --orphan poodle --detach bamboo
     +test_wt_add_excl --orphan poodle --no-checkout bamboo
     +test_wt_add_excl --orphan poodle bamboo main
3:  74cb091bb3 ! 4:  df4c1fa469 worktree add: Add hint to use --orphan when bad ref
    @@ advice.h: struct string_list;

      ## builtin/worktree.c ##
     @@ builtin/worktree.c: static int add(int ac, const char **av, const char *prefix)
    - 		 * If `branch` does not reference a valid commit, a new
    - 		 * worktree (and/or branch) cannot be created based off of it.
    - 		 */
    + 	if (opts.orphan) {
    + 		branch = new_branch;
    + 	} else if (!lookup_commit_reference_by_name(branch)) {
     +		advise_if_enabled(ADVICE_WORKTREE_ADD_ORPHAN,
    -+			"If you meant to create a worktree containing a new orphan branch\n"
    -+			"(branch with no commits) for this repository, e.g. '%s',\n"
    -+			"you can do so using the --orphan option:\n"
    ++			_("If you meant to create a worktree containing a new orphan branch\n"
    ++			"(branch with no commits) for this repository, you can do so\n"
    ++			"using the --orphan option:\n"
     +			"\n"
    -+			"	git worktree add --orphan %s %s\n"
    -+			"\n",
    -+			 new_branch, new_branch, path);
    ++			"	git worktree add --orphan %s %s\n"), new_branch, path);
      		die(_("invalid reference: %s"), branch);
      	} else if (new_branch) {
      		struct child_process cp = CHILD_PROCESS_INIT;
    @@ t/t2400-worktree-add.sh: test_expect_success '"add" worktree with orphan branch,
      	test_cmp expect .git/worktrees/orphan-with-lock-reason/locked
      '

    -+# Helper function to test hints for using --orphan in an empty repo.
     +test_wt_add_empty_repo_orphan_hint() {
    -+	local context="$1" &&
    -+	local opts="${@:2}" &&
    ++	local context="$1"
    ++	shift
    ++	local opts="$@"
     +	test_expect_success "'worktree add' show orphan hint in empty repo w/ $context" '
     +		test_when_finished "rm -rf empty_repo" &&
     +		GIT_DIR="empty_repo" git init --bare &&
    -+		test_must_fail git -C empty_repo worktree add $opts 2> actual &&
    ++		test_must_fail git -C empty_repo worktree add $opts foobar/ 2> actual &&
     +		grep "hint: If you meant to create a worktree containing a new orphan branch" actual
     +	'
     +}
     +
    -+test_wt_add_empty_repo_orphan_hint 'DWIM' foobar/
    -+test_wt_add_empty_repo_orphan_hint '-b' -b foobar_branch foobar/
    -+test_wt_add_empty_repo_orphan_hint '-B' -B foobar_branch foobar/
    ++test_wt_add_empty_repo_orphan_hint 'DWIM'
    ++test_wt_add_empty_repo_orphan_hint '-b' -b foobar_branch
    ++test_wt_add_empty_repo_orphan_hint '-B' -B foobar_branch
     +
      test_expect_success 'local clone from linked checkout' '
      	git clone --local here here-clone &&
--
2.38.2