wt: add -B/--branch option to checkout existing branch into new worktree

Adds the ability to checkout an existing branch (by its full name) into
a new worktree without prefix mangling. This is useful for pulling in
changes locally to validate a branch without switching the current branch.

Usage:
  wt switch -c -B fix/login-bug          # auto-derives name "login-bug"
  wt switch -c review -B fix/login-bug   # custom worktree name
  wt switch -c -B feature/pr-123 --fetch # fetch from remote first

Changes:
- Add -B/--branch and -f/--fetch options to `wt switch` command
- Add checkout_branch() and _derive_name_from_branch() to WorktreeManager
- Add fetch_branch() helper to git module
- Update list_worktrees() to check stored name for branched worktrees
- Add 18 new tests covering checkout, name derivation, and integration

https://claude.ai/code/session_0189JpNR1U5W4vguS2XTetXg

Author: claude

tools/wt-worktree/tests/test_cli.py

@@ -442,3 +442,91 @@ def test_detached_worktree_backward_compatibility(runner, initialized_repo, no_p
     # Should be able to find it by inferred name
     found_wt = manager.find_worktree_by_name("legacy")
     assert found_wt is not None
+
+
+# --- checkout branch (switch -c -B) tests ---
+
+
+def test_switch_checkout_branch(runner, initialized_repo, no_prompt):
+    """Test wt switch -c -B with existing branch."""
+    git.create_branch("fix/login-bug", "HEAD", initialized_repo)
+
+    result = runner.invoke(cli, ["switch", "-c", "-B", "fix/login-bug"])
+    assert result.exit_code == 0
+    assert "fix/login-bug" in result.output
+    assert "login-bug" in result.output
+
+
+def test_switch_checkout_branch_custom_name(runner, initialized_repo, no_prompt):
+    """Test wt switch -c <name> -B <branch>."""
+    git.create_branch("fix/login-bug", "HEAD", initialized_repo)
+
+    result = runner.invoke(cli, ["switch", "-c", "review", "-B", "fix/login-bug"])
+    assert result.exit_code == 0
+    assert "review" in result.output
+
+
+def test_switch_checkout_branch_nonexistent(runner, initialized_repo):
+    """Test wt switch -c -B with nonexistent branch."""
+    result = runner.invoke(cli, ["switch", "-c", "-B", "nonexistent/branch"])
+    assert result.exit_code == 3  # EXIT_GIT_ERROR
+    assert "does not exist" in result.output
+
+
+def test_switch_checkout_branch_requires_create(runner, initialized_repo):
+    """Test that -B requires -c flag."""
+    result = runner.invoke(cli, ["switch", "-B", "fix/login-bug"])
+    assert result.exit_code == 2
+    assert "requires" in result.output
+
+
+def test_switch_checkout_branch_no_detached(runner, initialized_repo):
+    """Test that -B cannot be used with -d."""
+    result = runner.invoke(cli, ["switch", "-c", "-B", "fix/login-bug", "-d"])
+    assert result.exit_code == 2
+    assert "cannot be used" in result.output.lower()
+
+
+def test_switch_checkout_branch_no_base(runner, initialized_repo):
+    """Test that -B cannot be used with -b."""
+    result = runner.invoke(cli, ["switch", "-c", "-B", "fix/login-bug", "-b", "main"])
+    assert result.exit_code == 2
+    assert "cannot be used" in result.output.lower()
+
+
+def test_switch_checkout_branch_shell_helper(runner, initialized_repo, no_prompt):
+    """Test wt switch -c -B with --shell-helper."""
+    git.create_branch("fix/login-bug", "HEAD", initialized_repo)
+
+    result = runner.invoke(cli, ["switch", "-c", "-B", "fix/login-bug", "--shell-helper"])
+    assert result.exit_code == 0
+    # Output should be just the path
+    output = result.output.strip()
+    assert "/" in output
+
+
+def test_switch_checkout_then_switch(runner, initialized_repo, no_prompt):
+    """Test that wt switch works after checkout."""
+    git.create_branch("fix/login-bug", "HEAD", initialized_repo)
+    runner.invoke(cli, ["switch", "-c", "-B", "fix/login-bug"])
+
+    # Should be able to switch to it by derived name
+    result = runner.invoke(cli, ["switch", "login-bug"])
+    assert result.exit_code == 0
+
+
+def test_switch_checkout_then_delete(runner, initialized_repo, no_prompt):
+    """Test that wt delete works after checkout."""
+    git.create_branch("fix/login-bug", "HEAD", initialized_repo)
+    runner.invoke(cli, ["switch", "-c", "-B", "fix/login-bug"])
+
+    # Should be able to delete by derived name
+    result = runner.invoke(cli, ["delete", "login-bug", "--force", "--keep-branch"])
+    assert result.exit_code == 0
+
+
+def test_switch_checkout_fetch_requires_branch(runner, initialized_repo):
+    """Test that --fetch requires -B."""
+    result = runner.invoke(cli, ["switch", "-c", "feat", "--fetch"])
+    assert result.exit_code == 2
+    assert "requires" in result.output

tools/wt-worktree/tests/test_worktree.py

@@ -183,3 +183,93 @@ def test_find_by_full_branch_name(manager):
     assert wt1 is not None
     assert wt2 is not None
     assert wt1["path"] == wt2["path"]
+
+
+# --- checkout_branch tests ---
+
+
+def test_derive_name_from_branch():
+    """Test name derivation from branch names."""
+    derive = WorktreeManager._derive_name_from_branch
+    assert derive("fix/login-bug") == "login-bug"
+    assert derive("feature/add-auth") == "add-auth"
+    assert derive("origin/feature/pr-123") == "pr-123"
+    assert derive("main") == "main"
+    assert derive("claude/some-branch") == "some-branch"
+    assert derive("origin/main") == "main"
+    assert derive("a/b/c") == "c"
+
+
+def test_checkout_branch(manager, git_repo):
+    """Test checking out an existing branch into a new worktree."""
+    git.create_branch("fix/login-bug", "HEAD", git_repo)
+
+    wt_path = manager.checkout_branch("fix/login-bug")
+
+    assert wt_path.exists()
+    wt = manager.find_worktree_by_name("login-bug")
+    assert wt is not None
+    assert wt["branch"] == "fix/login-bug"
+
+
+def test_checkout_branch_custom_name(manager, git_repo):
+    """Test checkout with a custom worktree name."""
+    git.create_branch("fix/login-bug", "HEAD", git_repo)
+
+    wt_path = manager.checkout_branch("fix/login-bug", name="review-login")
+
+    assert wt_path.exists()
+    wt = manager.find_worktree_by_name("review-login")
+    assert wt is not None
+    assert wt["branch"] == "fix/login-bug"
+
+
+def test_checkout_nonexistent_branch(manager, git_repo):
+    """Test checkout of a branch that doesn't exist."""
+    with pytest.raises(git.GitError, match="does not exist"):
+        manager.checkout_branch("nonexistent/branch")
+
+
+def test_checkout_branch_already_has_worktree(manager, git_repo):
+    """Test checkout of a branch that already has a worktree."""
+    git.create_branch("fix/login-bug", "HEAD", git_repo)
+    manager.checkout_branch("fix/login-bug")
+
+    with pytest.raises(git.GitError, match="already has a worktree"):
+        manager.checkout_branch("fix/login-bug")
+
+
+def test_checkout_branch_findable_by_derived_name(manager, git_repo):
+    """Test that checked-out worktree is findable by its derived name."""
+    git.create_branch("claude/my-feature", "HEAD", git_repo)
+    manager.checkout_branch("claude/my-feature")
+
+    # Should be findable by derived name
+    wt = manager.find_worktree_by_name("my-feature")
+    assert wt is not None
+
+    # Should also be findable by full branch name
+    wt2 = manager.find_worktree_by_name("claude/my-feature")
+    assert wt2 is not None
+    assert wt["path"] == wt2["path"]
+
+
+def test_checkout_branch_appears_in_list(manager, git_repo):
+    """Test that checked-out worktree appears in list with correct name."""
+    git.create_branch("fix/login-bug", "HEAD", git_repo)
+    manager.checkout_branch("fix/login-bug")
+
+    worktrees = manager.list_worktrees()
+    names = [wt["name"] for wt in worktrees]
+    assert "login-bug" in names
+
+
+def test_checkout_branch_name_conflict(manager, git_repo):
+    """Test checkout when derived name conflicts with existing path."""
+    git.create_branch("fix/bug", "HEAD", git_repo)
+    git.create_branch("hotfix/bug", "HEAD", git_repo)
+
+    manager.checkout_branch("fix/bug")
+
+    with pytest.raises(git.GitError, match="already exists"):
+        manager.checkout_branch("hotfix/bug")

tools/wt-worktree/wt/cli.py

@@ -87,17 +87,68 @@ def init(ctx: Context, prefix: str, path_pattern: str):
 @click.argument("name", required=False)
 @click.option("-c", "--create", is_flag=True, help="Create worktree if it doesn't exist")
 @click.option("-b", "--base", help="Base branch for new worktree")
+@click.option("-B", "--branch", "checkout_branch", default=None,
+              help="Checkout an existing branch into a new worktree (use with -c)")
+@click.option("-f", "--fetch", is_flag=True, help="Fetch branch from remote before checkout")
 @click.option("-d", "--detached", is_flag=True, help="Create in detached HEAD state")
 @click.option("--shell-helper", is_flag=True, hidden=True,
               help="Internal flag for shell integration")
 @pass_context
 def switch(ctx: Context, name: Optional[str], create: bool, base: Optional[str],
-          detached: bool, shell_helper: bool):
-    """Switch to a worktree, optionally creating it."""
+          checkout_branch: Optional[str], fetch: bool, detached: bool, shell_helper: bool):
+    """Switch to a worktree, optionally creating it.
+
+    Use -B/--branch to checkout an existing branch into a new worktree:
+
+    \b
+        wt switch -c -B fix/login-bug
+        wt switch -c review -B fix/login-bug
+        wt switch -c -B fix/login-bug --fetch
+    """
     if not ctx.repo_root or not ctx.manager:
         error("Not in a git repository.", EXIT_GIT_ERROR)
         return
 
+    # Validate flag combinations
+    if checkout_branch and not create:
+        error("--branch/-B requires --create/-c", EXIT_INVALID_ARGS)
+        return
+
+    if checkout_branch and detached:
+        error("--branch/-B cannot be used with --detached/-d", EXIT_INVALID_ARGS)
+        return
+
+    if checkout_branch and base:
+        error("--branch/-B cannot be used with --base/-b", EXIT_INVALID_ARGS)
+        return
+
+    if fetch and not checkout_branch:
+        error("--fetch/-f requires --branch/-B", EXIT_INVALID_ARGS)
+        return
+
+    # Handle checkout of existing branch
+    if checkout_branch:
+        from .worktree import WorktreeManager
+
+        try:
+            wt_path = ctx.manager.checkout_branch(checkout_branch, name, fetch)
+            display_name = name if name else WorktreeManager._derive_name_from_branch(checkout_branch)
+
+            # Record current worktree as previous
+            current_wt = ctx.manager.get_current_worktree()
+            if current_wt:
+                ctx.previous_worktree_file.write_text(str(current_wt["path"]))
+
+            if shell_helper:
+                print(wt_path)
+            else:
+                success(f"Checked out '{checkout_branch}' into worktree '{display_name}'")
+                info(f"Run: cd {wt_path}")
+
+        except git.GitError as e:
+            error(str(e), EXIT_GIT_ERROR)
+        return
+
     # Handle special names
     if name == "-":
         # Switch to previous worktree

tools/wt-worktree/wt/git.py

@@ -493,6 +493,21 @@ def fetch_remote(remote: str = "origin", path: Optional[Path] = None):
     run_git(["fetch", remote], cwd=path)
 
 
+def fetch_branch(branch: str, remote: str = "origin", path: Optional[Path] = None):
+    """
+    Fetch a specific branch from remote.
+
+    Args:
+        branch: Branch name to fetch
+        remote: Remote name
+        path: Repository path
+
+    Raises:
+        GitError: If fetch fails
+    """
+    run_git(["fetch", remote, branch], cwd=path)
+
+
 def enable_worktree_config(path: Path):
     """
     Enable worktree-specific config support.