Git worktree manager - make worktrees as effortless as branches
npm install @kianax/wtA fast, interactive TUI for managing git worktrees. Makes worktrees as effortless as branches.
``bash`
npm install -g @kianax/wt
Or build from source (requires Bun):
`bash`
bun install && bun run build
cp wt /usr/local/bin/
Shell integration enables wt to change your working directory when selecting a worktree. Without it, selections just print the path.
Bash/Zsh - add to ~/.bashrc or ~/.zshrc:
`bash`
eval "$(wt shell-init bash)" # or zsh
Fish - add to ~/.config/fish/config.fish:
`fish`
wt shell-init fish | source
The TUI will prompt you to set this up on first run.
`bash`
wt # Open interactive TUI
wt new
wt cd
wt rm
wt mv
wt ls # List all worktrees
wt current # Show current worktree name
`bashCreate with options
wt new feature --base main # Branch from specific base
wt new feature --branch feat/foo # Custom branch name
wt new feature --detach # Detached HEAD (no branch)
TUI Keybindings
| Key | Action |
|-----|--------|
|
j/k or ↑/↓ | Navigate |
| Enter | Select worktree |
| n | New worktree |
| d | Delete worktree |
| r | Rename worktree |
| i | Show details |
| s | Settings |
| q | Quit |Status Indicators
The TUI shows status for each worktree:
| Status | Meaning |
|--------|---------|
|
dirty | Uncommitted changes |
| ahead | Commits ahead of comparison branch |
| behind | Commits behind comparison branch |
| diverged | Both ahead and behind |
| synced | Up-to-date with comparison branch |
| merged | Branch merged into comparison branch |
| stale | No commits in 30+ days |Sync status compares against
origin/main by default (using local refs—no fetch). Falls back to origin/master, then local main/master if remote doesn't exist.Press
i on a worktree to see which branch it's comparing against (e.g., ↑3 ahead (vs origin/main)).To customize the comparison branch, press
s to open Settings or edit ~/.config/wt/config.json:`json
{
"defaults": {
"comparisonBranch": "origin/develop"
}
}
`How It Works
Worktrees are stored in
~/.worktrees/ by default:`
~/.worktrees/
github.com-user-repo/
feature-auth/
bugfix-login/
`The repo ID is derived from your git remote URL (e.g.,
github.com-user-repo).Configuration
All configuration is in
~/.config/wt/config.json:`json
{
"defaults": {
"branchPrefix": "feature/",
"staleDays": 30
},
"repos": {
"github.com-user-repo": {
"branchPrefix": "feat/"
}
}
}
`Use
repos` to override settings for specific repositories (keyed by repo ID).MIT