wt
Manage git worktrees with the wt CLI - create, switch, list, and delete worktrees with automatic dependency installation and graphite tracking
SKILL.mdskill-flow/data/skills-refined-36k/skillsmp/wt/SKILL.md
GitHubWhen to Use This Skill
Proactively use this skill when:
- User wants to create a new feature branch or worktree
- User wants to switch between worktrees
- User wants to list existing worktrees
- User wants to clean up or delete a worktree
- User mentions working on multiple branches simultaneously
Overview
The wt CLI is a git worktree management tool that automates:
- Creating worktrees in a standardized location
- Setting up dependencies with
bun install - Tracking branches with graphite (
gt track) - Copying files specified in
.worktreeinclude - Running type checks before creating worktrees
CLI Reference
Create a Worktree
wt create <path> [-b <branch>] [-p parent] [-r]
wt create -r <workspace-name> [-b <branch>] [-p parent]
Creates a new worktree with automatic setup:
- Runs type check (
bun run check-types) to ensure main branch is clean - Creates worktree at the specified path
- Copies files from
.worktreeincludeif present - Runs
bun installto set up dependencies - Tracks branch with graphite using specified parent (default:
develop)
Arguments:
<path>- Path where the worktree should be created (required unless using-r)-b, --branch <branch>- Name of the branch to create (optional, defaults to last component of path)-p, --parent <parent>- Parent branch for graphite tracking (default:develop)-r, --ralph- Create in~/.ralph/projects/<repo>/<workspace-name>directory
Examples:
wt create ../deal-deploy-feature-auth # Branch: feature-auth, Parent: develop
wt create ../deal-deploy-fix-login -p main # Branch: fix-login, Parent: main
wt create ~/projects/deal-deploy-ui -b custom-name --parent main # Branch: custom-name, Parent: main
wt create -r workspace-1 # Ralph: ~/.ralph/projects/deal-deploy/workspace-1, Branch: workspace-1
wt create -r workspace-1 -b feature-auth -p main # Ralph with custom branch and parent
Notes:
- Path can be relative or absolute
- If
-bis not specified, branch name is inferred from the last component of the path/workspace name - The
-rflag automatically creates worktrees in~/.ralph/projects/<repo>/for easier project organization - If worktree already exists at the path, suggests using
wt goinstead - Type check must pass before worktree creation proceeds
- Automatically changes to the new worktree directory on success
Switch to a Worktree
wt go <branch>
Changes to an existing worktree directory.
Arguments:
<branch>- Name of the branch/worktree to switch to (required)
Examples:
wt go feature-auth
wt go fix-login
Notes:
- Worktree must already exist
- Works with worktrees in any location (standard paths, ralph paths, custom paths)
- If worktree doesn't exist, suggests using
wt createinstead - Changes current directory to the worktree location
- Autocomplete available - press Tab to see available branches
List Worktrees
wt list
wt ls
Shows all git worktrees with their paths and branches.
Examples:
wt list
wt ls
Output: Standard git worktree list output showing paths, commit hashes, and branches
Delete a Worktree
wt delete <branch> [-f]
Removes a worktree and its associated branch.
Arguments:
<branch>- Name of the branch/worktree to delete (required)-f, --force- Force deletion even if worktree has uncommitted changes
Examples:
wt delete feature-auth # Normal deletion
wt delete feature-auth -f # Force deletion
wt delete feature-auth --force # Force deletion
Notes:
- Worktree must exist
- Works with worktrees in any location (standard paths, ralph paths, custom paths)
- Without
-f, deletion fails if there are uncommitted changes - Use
-fcautiously as it will discard uncommitted work - Autocomplete available - press Tab to see available branches
Worktree Include File
The .worktreeinclude file (optional) specifies files/patterns to copy to new worktrees:
Example .worktreeinclude:
.env
.env.local
config/*.local.json
# Comments are ignored
Behavior:
- Each line is a glob pattern relative to repo root
- Files matching patterns are copied to the new worktree
- Preserves directory structure
- Lines starting with
#are ignored - Blank lines are ignored
Workflow Examples
Starting a new feature
# From main repo
wt create ../deal-deploy-feature-auth
# Automatically:
# - Checks types
# - Creates worktree at ../deal-deploy-feature-auth
# - Creates branch named 'feature-auth' (inferred from path)
# - Copies .env and other included files
# - Runs bun install
# - Tracks with graphite (parent: develop)
# - Switches to new worktree
# Start coding!
Using Ralph directories for organized workspaces
# Create a ralph worktree
wt create -r workspace-1
# Automatically:
# - Creates worktree at ~/.ralph/projects/deal-deploy/workspace-1
# - Creates branch named 'workspace-1'
# - Rest is the same as above
# Custom branch name with ralph
wt create -r workspace-1 -b feature-auth
# Path: ~/.ralph/projects/deal-deploy/workspace-1
# Branch: feature-auth
Working on a hotfix from main
wt create ../deal-deploy-hotfix-critical -p main
# Creates worktree tracking main branch
# Branch name 'hotfix-critical' inferred from path
Switching between features
wt go feature-auth # Switch to auth feature
wt go feature-ui # Switch to UI feature
wt go main # Switch back to main worktree
Cleaning up completed work
wt delete feature-auth # After merging feature
wt list # See remaining worktrees
Checking all active worktrees
wt ls
# Example output:
# /home/user/myrepo abc123 [main]
# /home/user/myrepo-feature-auth def456 [feature-auth]
# /home/user/myrepo-feature-ui ghi789 [feature-ui]
Integration Points
Type Checking
- Runs
bun run check-typesbefore creating worktrees - Prevents creating worktrees when main branch has type errors
- Ensures clean starting point for new work
Graphite
- Automatically runs
gt track -p <parent>after worktree creation - Integrates worktree workflow with graphite stacking
- Default parent:
develop - Override with
-pflag
Bun
- Uses
bun installfor dependency installation - Runs in each new worktree automatically
- Ensures dependencies are up to date
Error Handling
Not in a git repository:
Error: Not in a git repository
Solution: Run from within a git repository
Type check fails:
Type check failed. Fix errors before creating worktree.
Solution: Fix type errors in current worktree before creating new one
Worktree already exists:
Worktree already exists at ../myrepo-feature-auth
Use: wt go feature-auth
Solution: Use wt go to switch to existing worktree
Worktree not found:
Worktree 'feature-auth' not found
Use: wt create feature-auth
Solution: Create the worktree first with wt create
Instructions for Claude
- Determine the user's intent - What do they want to do with worktrees?
- Check current context - Are they in a git repository? What's the main repo name?
- Run the appropriate wt command using the Bash tool
- Handle errors gracefully - Suggest fixes based on error messages
- Report the outcome - Clearly communicate what happened and next steps
Common Patterns
User wants to start new work:
wt create ../deal-deploy-feature-name
User wants to work from a different parent branch:
wt create ../deal-deploy-feature-name -p main
User wants a different branch name than the path:
wt create ../deal-deploy-workspace-1 -b feature-name
User wants to see what they're working on:
wt ls
User finished with a feature:
wt delete feature-name
User wants to switch context:
wt go other-feature