[PATCH v4 0/3] 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 three parts:
  * adding `-B` to the usage docs (noticed during dev and it seemed too small
    to justify a separate submission)
  * 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 v3:
  * Fix mistake in SYNOPSIS and `--help`. Patch for this change can be found
    in [2], by courtesy of Ævar Arnfjörð Bjarmason.
  * Collapsed sequential if statements into if-else chain & simplified
    conditions as requested in [2].
  * Simplified tests for mutually exclusive options and removed duplicate
    `-B/--detach` test case. Patch for this change can be found in [3],
    by courtesy of Ævar Arnfjörð Bjarmason.
  * Remove references to `git-switch`. Behavior is now explained fully in docs
    instead. Changes to the docs suggested in [4], by courtesy of Eric Sunshine.
  * Updated test case to use `test_path_is_missing` instead of `! test -d` [5].
  * Updated signature for `make_worktree_orphan()` and changed
    `const char *orphan_branch` in `struct add_opts` to `int orphan` (boolean)
    to simplify the patch and maintain consistency with other flags [6].
  * Added hint to common cases where `--orphan` is desired [7] to address
    concerns brought up in [8][9]. Slight change from `HEAD` to `branch`.
  * Added the new advice to the docs, advice.c/h, and using
    `advise_if_enabled()` as requested in [10].
  * Added tests to verify `--lock` and `--reason` work properly with
    the newly added `--orphan` flag.
  * Added tests to verify that the orphan advise [7] is emitted only at the
    proper times.
  * Added tests to verify the changes [7] do not interfere with existing
    behavior. ex: creating a worktree from a remote branch when HEAD is
    an orphan.

1. https://stackoverflow.com/a/68717229/15064705/
2. https://lore.kernel.org/git/221115.86edu3kfqz.gmgdl@evledraar.gmail.com/
3. https://lore.kernel.org/git/221116.86a64rkdcj.gmgdl@evledraar.gmail.com/
4. https://lore.kernel.org/git/CAPig+cQiyd9yGE_XpPZmzLQnNDMypnrEgkV7nqRZZn3j6E0APQ@mail.gmail.com/
5. https://lore.kernel.org/git/221115.86iljfkjjo.gmgdl@evledraar.gmail.com/
6. https://lore.kernel.org/git/20221119025701.syuscuoqjuqhqsoz@phi/
7. https://lore.kernel.org/git/20221119034728.m4kxh4tdpof7us7j@phi/
8. https://lore.kernel.org/git/CAPig+cTTn764ObHJuw8epOtBdTUwocVRV=tLieCa4zf-PGCegw@mail.gmail.com/
9. https://lore.kernel.org/git/221117.86sfihj3mw.gmgdl@evledraar.gmail.com/
10. https://lore.kernel.org/git/221123.86a64ia6bx.gmgdl@evledraar.gmail.com/

Jacob Abel (3):
  worktree add: Include -B in usage docs
  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              | 81 ++++++++++++++++++++++++++---
 t/t2400-worktree-add.sh         | 90 +++++++++++++++++++++++++++++----
 6 files changed, 176 insertions(+), 18 deletions(-)

Range-diff against v3:
1:  f35d78cfb4 = 1:  f35d78cfb4 worktree add: Include -B in usage docs
2:  c040c87c6d ! 2:  8b1cdf1322 worktree add: add --orphan flag
    @@ Commit message

         The original reason this feature was implemented was to allow a user
         to initialise a new repository using solely the worktree oriented
    -    workflow. Example usage included below.
    +    workflow.

    -    $ GIT_DIR=".git" git init --bare
    -    $ git worktree add --orphan master master/
    +    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: 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/
    +    Preparing worktree (new branch 'main')
    +    %

         Signed-off-by: Jacob Abel <jacobabel@nullpo.dev>
    +    Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>

      ## 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 | --orphan] <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]]
      'git worktree lock' [--reason <string>] <worktree>
      'git worktree move' <worktree> <new-path>
    @@ Documentation/git-worktree.txt: exist, a new branch based on `HEAD` is automatic
     +$ git worktree add --orphan <branch> <path>
     +------------
     ++
    -+Create a worktree containing an orphan branch named `<branch>` with a
    -+clean working directory.  See `--orphan` in linkgit:git-switch[1] for
    -+more details.
    ++Create a worktree containing no files, with an empty index, and associated
    ++with a new orphan branch named `<branch>`. The first commit made on this new
    ++branch will have no parents and will be the root of a new history disconnected
    ++from any other branches.

      list::

    @@ Documentation/git-worktree.txt: This can also be set up as the default behaviour
      	remove.

     +--orphan <new-branch>::
    -+	With `add`, create a new orphan branch named `<new-branch>` in the new
    -+	worktree. See `--orphan` in linkgit:git-switch[1] for details.
    ++	With `add`, make the new worktree and index empty, associating
    ++	the worktree with a new orphan branch named `<new-branch>`.
     +
      --porcelain::
      	With `list`, output in an easy-to-parse format for scripts.
    @@ 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 | --orphan] <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>")
    ++
      #define BUILTIN_WORKTREE_LIST_USAGE \
      	N_("git worktree list [-v | --porcelain [-z]]")
      #define BUILTIN_WORKTREE_LOCK_USAGE \
    @@ builtin/worktree.c: struct add_opts {
      	int detach;
      	int quiet;
      	int checkout;
    -+	const char *orphan_branch;
    ++	int orphan;
      	const char *keep_locked;
      };

    @@ builtin/worktree.c: static int checkout_worktree(const struct add_opts *opts,
      	return run_command(&cp);
      }

    -+static int make_worktree_orphan(const struct add_opts *opts,
    ++static int make_worktree_orphan(const char * ref, const struct add_opts *opts,
     +				struct strvec *child_env)
     +{
     +	int ret;
    @@ builtin/worktree.c: static int checkout_worktree(const struct add_opts *opts,
     +	struct child_process cp = CHILD_PROCESS_INIT;
     +	cp.git_cmd = 1;
     +
    -+	validate_new_branchname(opts->orphan_branch, &symref, 0);
    ++	validate_new_branchname(ref, &symref, 0);
     +	strvec_pushl(&cp.args, "symbolic-ref", "HEAD", symref.buf, NULL);
     +	if (opts->quiet)
     +		strvec_push(&cp.args, "--quiet");
    @@ 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_branch)
    ++	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_worktree(const char *path, const char *refnam
      	if (ret)
      		goto done;

    -+	if (opts->orphan_branch &&
    -+	    (ret = make_worktree_orphan(opts, &child_env)))
    ++	if (opts->orphan &&
    ++	    (ret = make_worktree_orphan(refname, opts, &child_env)))
     +		goto done;
     +
      	if (opts->checkout &&
    @@ builtin/worktree.c: static int add_worktree(const char *path, const char *refnam
      	 * is_junk is cleared, but do return appropriate code when hook fails.
      	 */
     -	if (!ret && opts->checkout) {
    -+	if (!ret && opts->checkout && !opts->orphan_branch) {
    ++	if (!ret && opts->checkout && !opts->orphan) {
      		struct run_hooks_opt opt = RUN_HOOKS_OPT_INIT;

      		strvec_pushl(&opt.env, "GIT_DIR", "GIT_WORK_TREE", NULL);
    +@@ builtin/worktree.c: static int add(int ac, const char **av, const char *prefix)
    + 	char *path;
    + 	const char *branch;
    + 	const char *new_branch = NULL;
    ++	const char *orphan_branch = NULL;
    + 	const char *opt_track = NULL;
    + 	const char *lock_reason = NULL;
    + 	int keep_locked = 0;
     @@ builtin/worktree.c: 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_STRING(0, "orphan", &opts.orphan_branch, N_("branch"),
    ++		OPT_STRING(0, "orphan", &orphan_branch, N_("branch"),
     +			   N_("new unparented branch")),
      		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", &keep_locked, N_("keep the new working tree locked")),
     @@ builtin/worktree.c: static int add(int ac, const char **av, const char *prefix)
    + 	memset(&opts, 0, sizeof(opts));
    + 	opts.checkout = 1;
      	ac = parse_options(ac, av, prefix, options, git_worktree_add_usage, 0);
    ++	opts.orphan = !!orphan_branch;
      	if (!!opts.detach + !!new_branch + !!new_branch_force > 1)
      		die(_("options '%s', '%s', and '%s' cannot be used together"), "-b", "-B", "--detach");
    -+	if (!!opts.detach + !!new_branch + !!new_branch_force + !!opts.orphan_branch > 1)
    ++	if (!!opts.detach + !!opts.orphan + !!new_branch + !!new_branch_force > 1)
     +		die(_("options '%s', '%s', '%s', and '%s' cannot be used together"),
     +		    "-b", "-B", "--orphan", "--detach");
    -+	if (opts.orphan_branch && opt_track)
    ++	if (opts.orphan && opt_track)
     +		die(_("'%s' and '%s' cannot be used together"), "--orphan", "--track");
    -+	if (opts.orphan_branch && !opts.checkout)
    ++	if (opts.orphan && !opts.checkout)
     +		die(_("'%s' and '%s' cannot be used together"), "--orphan",
     +		    "--no-checkout");
    ++	if (opts.orphan && ac == 2)
    ++		die(_("'%s' and '%s' cannot be used together"), "--orphan",
    ++		    _("<commit-ish>"));
      	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 (ac < 2 && !new_branch && !opts.detach) {
    -+	/*
    -+	 * As the orphan cannot be created until the contents of branch
    -+	 * are staged, opts.orphan_branch should be treated as both a boolean
    -+	 * indicating that `--orphan` was selected and as the name of the new
    -+	 * orphan branch from this point on.
    -+	 */
    -+	if (opts.orphan_branch) {
    -+		new_branch = opts.orphan_branch;
    -+	}
    -+
    -+	if (ac < 2 && !new_branch && !opts.detach && !opts.orphan_branch) {
    ++	if (opts.orphan) {
    ++		new_branch = orphan_branch;
    ++	} else if (ac < 2 && !new_branch && !opts.detach) {
      		const char *s = dwim_branch(path, &new_branch);
      		if (s)
      			branch = s;
    @@ builtin/worktree.c: static int add(int ac, const char **av, const char *prefix)
      		print_preparing_worktree_line(opts.detach, branch, new_branch, !!new_branch_force);

     -	if (new_branch) {
    -+	if (new_branch && !opts.orphan_branch) {
    ++	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;
      		cp.git_cmd = 1;
      		strvec_push(&cp.args, "branch");

      ## t/t2400-worktree-add.sh ##
    -@@ t/t2400-worktree-add.sh: test_expect_success '"add" -B/--detach mutually exclusive' '
    - 	test_must_fail git worktree add -B poodle --detach bamboo main
    +@@ 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" --orphan/-b mutually exclusive' '
    -+	test_must_fail git worktree add --orphan poodle -b poodle bamboo
    -+'
    -+
    -+test_expect_success '"add" --orphan/-B mutually exclusive' '
    -+	test_must_fail git worktree add --orphan poodle -B poodle bamboo
    -+'
    -+
    -+test_expect_success '"add" --orphan/--detach mutually exclusive' '
    -+	test_must_fail git worktree add --orphan poodle --detach bamboo
    -+'
    -+
    -+test_expect_success '"add" --orphan/--no-checkout mutually exclusive' '
    -+	test_must_fail git worktree add --orphan poodle --no-checkout bamboo
    -+'
    -+
    -+test_expect_success '"add" -B/--detach mutually exclusive' '
    -+	test_must_fail git worktree add -B poodle --detach bamboo main
    -+'
    -+
    +-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
    ++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
    +
      test_expect_success '"add -B" fails if the branch is checked out' '
      	git rev-parse newmain >before &&
    - 	test_must_fail git worktree add -B newmain bamboo main &&
     @@ t/t2400-worktree-add.sh: test_expect_success 'add --quiet' '
      	test_must_be_empty actual
      '
    @@ t/t2400-worktree-add.sh: test_expect_success 'add --quiet' '
     +	test_when_finished "git worktree remove -f -f orphandir" &&
     +	git worktree add -b existingbranch orphandir main &&
     +	test_must_fail git worktree add --orphan existingbranch orphandir2 &&
    -+	test ! -d orphandir2
    ++	test_path_is_missing orphandir2
     +'
     +
     +test_expect_success '"add --orphan" with empty repository' '
    @@ t/t2400-worktree-add.sh: test_expect_success 'add --quiet' '
     +	git -C empty_repo/worktreedir symbolic-ref HEAD >actual &&
     +	test_cmp expected actual
     +'
    ++
    ++test_expect_success '"add" worktree with orphan branch and lock' '
    ++	git worktree add --lock --orphan orphanbr orphan-with-lock &&
    ++	test_when_finished "git worktree unlock orphan-with-lock || :" &&
    ++	test -f .git/worktrees/orphan-with-lock/locked
    ++'
    ++
    ++test_expect_success '"add" worktree with orphan branch, lock, and reason' '
    ++	lock_reason="why not" &&
    ++	git worktree add --detach --lock --reason "$lock_reason" orphan-with-lock-reason main &&
    ++	test_when_finished "git worktree unlock orphan-with-lock-reason || :" &&
    ++	test -f .git/worktrees/orphan-with-lock-reason/locked &&
    ++	echo "$lock_reason" >expect &&
    ++	test_cmp expect .git/worktrees/orphan-with-lock-reason/locked
    ++'
     +
      test_expect_success 'local clone from linked checkout' '
      	git clone --local here here-clone &&
      	( cd here-clone && git fsck )
    +@@ t/t2400-worktree-add.sh: setup_remote_repo () {
    + 	)
    + }
    +
    ++test_expect_success '"add" <path> <remote/branch> w/ no HEAD' '
    ++	test_when_finished rm -rf repo_upstream repo_local foo &&
    ++	setup_remote_repo repo_upstream repo_local &&
    ++	git -C repo_local config --bool core.bare true &&
    ++	git -C repo_local branch -D main &&
    ++	git -C repo_local worktree add ./foo repo_upstream/foo
    ++'
    ++
    + test_expect_success '--no-track avoids setting up tracking' '
    + 	test_when_finished rm -rf repo_upstream repo_local foo &&
    + 	setup_remote_repo repo_upstream repo_local &&
-:  ---------- > 3:  74cb091bb3 worktree add: Add hint to use --orphan when bad ref
--
2.37.4