abhi-arya1/using-wt

wt — Git Worktree Sandbox Manager

CLI tool that creates isolated git worktree checkouts ("sandboxes") locally or on remote SSH hosts. Built with TypeScript + Commander.

Core Concepts

• Sandbox: An isolated git worktree checkout with a unique name, ID (nanoid), host, and path
• Host: Either "local" (built-in) or a registered remote SSH target
• Mirror: A bare --mirror clone stored at .wt/mirrors/<repoId>.git (local) or <root>/mirrors/ (remote)
• Config: ~/.config/wt/config.json — stores hosts, sandboxes, default host

Directory Layout

.wt/                          # Local (inside repo root, gitignored)
  mirrors/<repoId>.git/       # bare --mirror clone
  sandboxes/<sandboxName>/      # worktree checkout
  meta/<sandboxName>.json       # metadata

<remote-root>/                # Remote (user-configured)
  mirrors/<repoId>.git/
  sandboxes/<sandboxName>/
  meta/<sandboxName>.json

Commands

| Command | Description | |---|---| | wt up [name] | Create sandbox on a host. -H <host>, --branch <ref>. Auto-names from branch. | | wt local [name] | Shorthand for wt up on local host. | | wt enter <name> | Shell into sandbox. --tmux for persistent session. | | wt run <name> -- <cmd...> | Run command in sandbox. --json, --quiet. | | wt ls | List sandboxes. --host to filter. | | wt rm <name> | Remove sandbox (prompts confirmation, --yes to skip). | | wt rename <old> <new> | Rename a sandbox. | | wt status <name> | Show sandbox info (host, ref, path, age, tmux state). | | wt sessions | List active wt-* tmux sessions. | | wt gc | Remove stale sandboxes. --older-than 7d (default), --dry-run. | | wt doctor | Check prerequisites (git, bun/node, tmux) on a host. | | wt bootstrap | Report host readiness + install hints (read-only, installs nothing). | | wt host add [name] | Register remote host. Interactive mode if args omitted. | | wt host ls | List configured hosts (includes port mappings). | | wt host check <name> | Test SSH connectivity. | | wt host rm <name> | Remove host config. | | wt host map <name> <localPort> <hostPort> | Add port forwarding (-L) to a host. | | wt host unmap <name> <localPort> | Remove a port mapping. |

Common Workflows

Local sandbox:

cd my-project
wt local my-experiment        # Create from current repo
wt enter my-experiment        # Shell in
wt rm my-experiment           # Clean up

Remote sandbox:

wt host add prod --ssh [email protected] --root /srv/wt
wt doctor -H prod
wt up my-feature -H prod --branch feature/auth
wt enter my-feature --tmux
wt run my-feature -- make build

Port forwarding:

wt host map prod 3000 8080      # local:3000 -> remote:8080
wt host map prod 5432 5432      # forward postgres
wt enter my-feature             # mappings applied automatically
wt host unmap prod 3000         # remove mapping

Parallel branch testing:

wt up auth --branch feature/auth
wt up payments --branch feature/payments
wt run auth -- bun test
wt run payments -- bun test
wt gc --older-than 1d

Important Conventions

• All commands support --json for machine-readable output (errors: { "ok": false, "error": "..." })
• Host flag is -H (capital), not -h (which is --help)
• wt run uses -- to separate wt flags from the command to execute
• Sandbox names auto-derive from branch name if omitted (last segment after /, sanitized)
• Host names must match /^[a-z][a-z0-9_-]{0,31}$/
• wt up is idempotent — re-running with same name/host/repo returns existing sandbox
• .env* files from CWD are auto-copied into new sandboxes
• Config writes are concurrency-safe — all mutations use withConfig(fn) (proper-lockfile) in src/core/host/config.ts

Good-to-know

• wt up defaults to HEAD SHA (detached), not a branch ref. Branch name is only used for naming.
• Remote sandboxes require the origin to be cloneable from the remote host.
• wt enter --tmux and interactive commands call process.exit() — they take over the process.
• Local .wt/ resolves from repo root via git rev-parse --show-toplevel, even from subdirectories.