Git Worktrees
Git worktrees allow you to check out multiple branches simultaneously in separate directories.
Why Worktrees?
Development is often interrupted:
- A critical bug needs immediate attention
- A colleague needs a code review on their branch
- Your current task is put on hold
- You need to compare implementations side-by-side
Without worktrees, you’d stash changes, switch branches, lose context, and later struggle to remember where you were. Worktrees let you keep everything in place.
Native Git vs Workareas
Native git worktree commands are verbose:
# Native git - hard to remember
git worktree add [-f] [--detach] [--checkout] [--lock] [-b <branch>] <path> [<commit-ish>]
# Workareas - simple and tracked
wa add --wt=bugfix --alias=bf --bn=hotfix-123Worktree Commands
| Command | Description |
|---|---|
wa ls | List all worktrees on current machine |
wa ls --aliases | List only worktrees with aliases |
wa add --wt=name --bn=branch | Create new worktree |
wa rm --wt=path | Remove a worktree from tracking |
wa set --alias=shortname | Set alias for current worktree |
Worktree Data Model
When stored in CaseMgr, each worktree tracks:
| Field | Description |
|---|---|
| name | Display name (often from path or alias) |
| path | Filesystem path on the machine |
| machine_id | Hostname identifying which machine |
| os_type | Operating system (linux, macos, windows) |
| remote_origin | Git remote URL (links worktrees across machines) |
| branch | Current branch name |
| head | Current commit SHA |
| alias | Short name for quick navigation |
| workspace_filename | Associated VS Code workspace file |
Multi-Machine Support
With CaseMgr backend, worktrees are tracked per-machine using machine_id. The remote_origin field links the same repository across different machines.
# Export all worktrees (all machines) for backup
wa export wa --all > backup.json
# Import worktrees on a new machine
wa import wa --file=backup.json