|
| 1 | +--- |
| 2 | +name: wt |
| 3 | +description: "This skill should be used when the user asks about 'wt', 'worktree', 'worktrees', 'wt create', 'wt checkout', 'wt list', 'wt remove', 'wt pr', 'wt mr', or mentions managing git worktrees with wt. Also use when the user asks how wt works, how to use wt commands, or how to organize branches with worktrees." |
| 4 | +user-invocable: true |
| 5 | +--- |
| 6 | + |
| 7 | +# Working with wt - Git Worktree Manager |
| 8 | + |
| 9 | +wt is a fast Git worktree helper written in Go. It wraps `git worktree` with a convenient interface, organized directory structure, and smart defaults. Each branch gets its own directory — no stashing, no branch switching. |
| 10 | + |
| 11 | +## Core Philosophy |
| 12 | + |
| 13 | +**Never switch branches in the main checkout.** Always create a worktree for each task. This keeps the user's workspace clean and allows parallel work on multiple branches. |
| 14 | + |
| 15 | +## Commands |
| 16 | + |
| 17 | +| Command | Purpose | |
| 18 | +|---------|---------| |
| 19 | +| `wt create <branch> [base]` | Create a new branch in a worktree (defaults to main/master as base) | |
| 20 | +| `wt co <branch>` | Checkout an existing branch in a new worktree | |
| 21 | +| `wt co` | Interactive: fuzzy-search from available branches | |
| 22 | +| `wt ls` | List all worktrees | |
| 23 | +| `wt rm <branch>` | Remove a worktree | |
| 24 | +| `wt rm` | Interactive: fuzzy-search worktree to remove | |
| 25 | +| `wt pr [number\|url]` | Checkout a GitHub PR (requires `gh` CLI) | |
| 26 | +| `wt pr` | Interactive: fuzzy-search from open PRs | |
| 27 | +| `wt mr [number\|url]` | Checkout a GitLab MR (requires `glab` CLI) | |
| 28 | +| `wt mr` | Interactive: fuzzy-search from open MRs | |
| 29 | +| `wt status` | Color-coded overview of all worktrees | |
| 30 | +| `wt status --ci` | Include CI/CD pipeline status per branch | |
| 31 | +| `wt info` | Show active strategy, pattern, variables | |
| 32 | +| `wt config show` | Show effective config with sources | |
| 33 | +| `wt cleanup --stale` | Detect stale worktrees (deleted remotes, inactive commits) | |
| 34 | +| `wt prune` | Clean up stale worktree admin files | |
| 35 | +| `wt migrate` | Migrate worktrees to match configured paths | |
| 36 | +| `wt init` | Configure shell integration | |
| 37 | +| `wt examples` | Show practical examples | |
| 38 | + |
| 39 | +## Worktree Layout Strategies |
| 40 | + |
| 41 | +wt supports multiple strategies for organizing worktrees. Configure via `~/.config/wt/config.toml` or per-repo `.wt.toml`. |
| 42 | + |
| 43 | +| Strategy | Layout | |
| 44 | +|----------|--------| |
| 45 | +| `global` | `<root>/<repo>/<branch>` — all repos share one root | |
| 46 | +| `sibling-repo` | `../<repo>-worktrees/<branch>` — worktrees next to repo | |
| 47 | +| `parent-branches` | `../<branch>` — branches as siblings of main checkout | |
| 48 | + |
| 49 | +The `pattern` setting controls the path template. Variables: `{root}`, `{repo}`, `{branch}`, `{host}`, `{owner}`. |
| 50 | + |
| 51 | +## Configuration |
| 52 | + |
| 53 | +- Config file: `~/.config/wt/config.toml` (or `WT_CONFIG` / `--config`) |
| 54 | +- Per-repo override: `.wt.toml` in the repo root |
| 55 | +- Key settings: `root`, `strategy`, `pattern`, `separator` |
| 56 | +- Env overrides: `WORKTREE_ROOT`, `WORKTREE_STRATEGY`, `WORKTREE_PATTERN`, `WORKTREE_SEPARATOR` |
| 57 | + |
| 58 | +## Hooks |
| 59 | + |
| 60 | +wt supports pre/post hooks for `create`, `checkout`, `remove`, `pr`, and `mr` commands. |
| 61 | + |
| 62 | +Configure in `config.toml` or `.wt.toml`: |
| 63 | + |
| 64 | +```toml |
| 65 | +[hooks] |
| 66 | +post_create = ["cp .env $WT_PATH/.env"] |
| 67 | +post_checkout = ["echo 'Switched to $WT_BRANCH'"] |
| 68 | +``` |
| 69 | + |
| 70 | +Hook environment variables: `WT_PATH`, `WT_BRANCH`, `WT_MAIN`, `WT_REPO_NAME`, `WT_REPO_HOST`, `WT_REPO_OWNER`. Disable all hooks: `WT_HOOKS_DISABLED=1`. |
| 71 | + |
| 72 | +### Common Hook Recipes |
| 73 | + |
| 74 | +**Copy `.env` files from main worktree:** |
| 75 | + |
| 76 | +```toml |
| 77 | +[hooks] |
| 78 | +post_create = [ |
| 79 | + "test -f $WT_MAIN/.env && cp $WT_MAIN/.env $WT_PATH/.env || true" |
| 80 | +] |
| 81 | +post_checkout = [ |
| 82 | + "test -f $WT_MAIN/.env && cp $WT_MAIN/.env $WT_PATH/.env || true" |
| 83 | +] |
| 84 | +``` |
| 85 | + |
| 86 | +**Auto-install dependencies (Node.js):** |
| 87 | + |
| 88 | +```toml |
| 89 | +[hooks] |
| 90 | +post_create = ["cd $WT_PATH && npm install"] |
| 91 | +post_checkout = ["cd $WT_PATH && npm install"] |
| 92 | +``` |
| 93 | + |
| 94 | +**Auto-install dependencies (Python/uv):** |
| 95 | + |
| 96 | +```toml |
| 97 | +[hooks] |
| 98 | +post_create = ["cd $WT_PATH && uv sync"] |
| 99 | +post_checkout = ["cd $WT_PATH && uv sync"] |
| 100 | +``` |
| 101 | + |
| 102 | +**Launch Claude Code in tmux per worktree:** |
| 103 | + |
| 104 | +```toml |
| 105 | +[hooks] |
| 106 | +post_create = [ |
| 107 | + "tmux new-session -d -s \"$WT_REPO_NAME/$WT_BRANCH\" -c \"$WT_PATH\" \"claude -n '$WT_REPO_NAME/$WT_BRANCH'\" 2>/dev/null; echo \"tmux session: $WT_REPO_NAME/$WT_BRANCH\"" |
| 108 | +] |
| 109 | +pre_remove = [ |
| 110 | + "tmux kill-session -t \"$WT_REPO_NAME/$WT_BRANCH\" 2>/dev/null || true" |
| 111 | +] |
| 112 | +``` |
| 113 | + |
| 114 | +**Shared build cache (symlink `node_modules` across worktrees):** |
| 115 | + |
| 116 | +```toml |
| 117 | +[hooks] |
| 118 | +post_create = [ |
| 119 | + "mkdir -p $HOME/.cache/wt/$WT_REPO_NAME/node_modules && ln -sf $HOME/.cache/wt/$WT_REPO_NAME/node_modules $WT_PATH/node_modules && cd $WT_PATH && npm install" |
| 120 | +] |
| 121 | +``` |
| 122 | + |
| 123 | +**Deterministic dev server port per branch:** |
| 124 | + |
| 125 | +```toml |
| 126 | +[hooks] |
| 127 | +post_create = [ |
| 128 | + "printf 'PORT=%d\\n' $(( 3000 + $(printf '%s' \"$WT_BRANCH\" | cksum | cut -d' ' -f1) % 997 )) > $WT_PATH/.env.port" |
| 129 | +] |
| 130 | +``` |
| 131 | + |
| 132 | +## JSON Output |
| 133 | + |
| 134 | +Most commands support `--format json` for machine-readable output: |
| 135 | + |
| 136 | +```bash |
| 137 | +wt --format json list |
| 138 | +wt --format json info |
| 139 | +wt --format json config show |
| 140 | +wt --format json version |
| 141 | +``` |
| 142 | + |
| 143 | +## Shell Integration |
| 144 | + |
| 145 | +After `wt init`, the shell function auto-navigates to worktrees on create/checkout. As an agent, you won't get auto-cd — use the printed worktree path explicitly in subsequent operations. |
| 146 | + |
| 147 | +## Agent Workflow |
| 148 | + |
| 149 | +```bash |
| 150 | +# 1. Create worktree for a task |
| 151 | +wt create feat/my-feature |
| 152 | + |
| 153 | +# 2. Work in the worktree directory (path printed by wt create) |
| 154 | +# All file operations should use the worktree path |
| 155 | + |
| 156 | +# 3. Run tests, commit, push from the worktree |
| 157 | +go test ./... |
| 158 | +git add . && git commit -m "feat: my feature" |
| 159 | +git push -u origin feat/my-feature |
| 160 | + |
| 161 | +# 4. Create PR |
| 162 | +gh pr create --title "feat: my feature" --body "Description" |
| 163 | + |
| 164 | +# 5. Clean up after merge |
| 165 | +wt rm feat/my-feature |
| 166 | +``` |
| 167 | + |
| 168 | +## When Helping Users |
| 169 | + |
| 170 | +- If the user wants to work on a branch, suggest `wt create` or `wt co` instead of `git checkout` |
| 171 | +- Use `wt ls` to understand the current worktree layout |
| 172 | +- For PRs/MRs, use `wt pr` / `wt mr` — they resolve the branch name automatically |
| 173 | +- Use `wt status` to get an overview of all worktrees and their state |
| 174 | +- For non-interactive/agent contexts, always pass explicit arguments (e.g., `wt co <branch>`, not `wt co`) |
0 commit comments