Worktrees

Git Worktrees

Git worktrees enable checking out multiple branches simultaneously in separate directories. wa wraps the complex git worktree commands into simple, trackable operations backed by CaseMgr.

Why Worktrees?

Development interruptions are common: critical bugs requiring immediate attention, code review requests, tasks being put on hold, or needing to compare implementations side-by-side. Without worktrees, developers must stash changes, switch branches, lose context, and later struggle to recall their previous work. Worktrees preserve everything in place.

Native Git vs wa

# Native git - hard to remember
git worktree add [-f] [--detach] [--checkout] [--lock] [-b <branch>] <path> [<commit-ish>]

# wa - simple and tracked
wa add --bn=hotfix-123 --alias=hf

Worktree Commands

Command	Description
`wa ls wt`	List local worktrees
`wa ls wt --server`	List all worktrees from CaseMgr (all machines)
`wa ls wt --server --machine=hostname`	Filter by machine
`wa add --bn=branch --alias=name`	Create new worktree with branch and alias
`wa get wt --worktree`	Get current worktree root path
`wa get wt --case`	Show case linked to current worktree
`wa set wt --alias=shortname`	Set alias for current worktree
`wa set wt --assignCase="Case Name"`	Link worktree to a CaseMgr case (by name)
`wa rm wt --wt=path`	Remove a worktree
`wa code`	Open VS Code workspace for current worktree

Worktree Data Model

Each worktree stored in CaseMgr 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

Case Integration

Worktrees can be linked to CaseMgr cases for context tracking. When a worktree is linked to a case, file operations (upload, download, move) automatically target that case.

# Create a case and assign it to the current worktree
wa set wt --createCase --caseName="Feature X"

# Or assign an existing case by name
wa set wt --assignCase="Feature X"

# Check which case is linked
wa get wt --case

Multi-Machine Support

With CaseMgr as the backend, worktrees are tracked per-machine using machine_id. The remote_origin field connects the same repository across different machines.

# List worktrees from all machines
wa ls wt --server

# Export all worktrees for backup
wa export wa --all > backup.json

# Import worktrees on a new machine
wa import wa --file=backup.json