@gitsoufiane/wt

npm install -g @gitsoufiane/wt
wt feature-a        # new worktree at ~/.worktrees/<repo>/feature-a

Why wt

Plain Git needs several steps for each new worktree:

git fetch origin
git worktree add -b feature-a ../feature-a origin/main
cp .env ../feature-a/ && cd ../feature-a && npm install

wt feature-a does all of that:

• Safe base. Fetches the remote, then branches from the remote default branch. If origin/feature-a exists, it checks it out and tracks it.
• Ready to run. Copies untracked .env and .env.* files and runs the install for your lockfile (npm, pnpm, yarn, or bun), or your own hook.
• Easy cleanup. wt -D feature-a removes the worktree and the branch.
• Script and agent friendly. --json prints one JSON object on stdout.

Install

Requirements: Node.js 18+, Git, and fzf only for wt -s.

To install the latest code straight from GitHub, without npm releases:

npm install -g --allow-git=all github:gitsoufiane/wt        # main branch
npm install -g --allow-git=all github:gitsoufiane/wt#v0.4.0 # one tag

npm 12 blocks Git sources unless you pass --allow-git=all; older npm versions do not need it. Both commands put wt on your PATH. Run wt -v to check.

[!WARNING] The npm name wt-cli belongs to a different package. If you installed an older version of this tool as wt-cli, run npm uninstall -g wt-cli first, and never install wt-cli from the registry.

Commands

Flags:

Status messages go to stderr, with emoji, colors, and a spinner for each long step (fetch, worktree add, install). In a terminal, the spinner shows the last output line of the step; in CI or a pipe, the output streams as plain lines. NO_COLOR=1 turns colors off. stdout carries only the result: the path and cd line, or the JSON object with --json.

Daily use

$ wt feature-a

🌳 wt v0.3.0  creating worktree feature-a

   📦 repo    /Users/me/my-repo
   📁 target  /Users/me/.worktrees/my-repo/feature-a
✔ 🛰️  Fetching latest origin (0.8s)
   🌱 base    origin/main
✔ 🌿 Creating branch 'feature-a' from origin/main (61ms)
🔐 copied .env
✔ 📦 Installing dependencies (npm install) (4.2s)

✨ Worktree feature-a is ready in 5.3s

/Users/me/.worktrees/my-repo/feature-a
cd '/Users/me/.worktrees/my-repo/feature-a'

A program cannot change the directory of the shell that started it. Pick one:

• wt --shell feature-a opens a new shell inside the worktree.
• Add this line to ~/.bashrc or ~/.zshrc, then run wtc feature-a, wtc -s, or wtc -D. The wtc helper runs wt and moves your shell to the printed path:

eval "$(wt shell-init)"

wt -l marks the current worktree with ➜ and shows clean, changed, or missing folders. wt -l --json prints an array with path, branch, name, main, current, dirty, and missing.

Defaults

• Worktrees go in ~/.worktrees/<repo-name>/<branch>, also when you run wt from a linked worktree.
• If <remote>/<name> exists, wt <name> checks it out and tracks it, so you can open a teammate's branch. Otherwise the new branch has no upstream.
• If the fetch fails (for example, offline), wt warns and uses local refs.
• --base <ref> wins over everything. Without it, the base ref order for new branches is: <remote>/<name> (tracked), WT_BASE, wt.base, the remote default branch, origin/this, origin/main, origin/master, then HEAD.
• The remote is wt.remote, default origin.
• Setup runs wt.hook if set. Otherwise it runs the install for the detected lockfile.

Config

Set defaults per repo:

git config wt.root ~/Desktop/worktree/my-repo
git config wt.base origin/this
git config wt.remote origin
git config wt.hook 'yarn install'
git config wt.copyEnv false

One-off environment overrides:

WT_ROOT=~/Desktop/worktree/my-repo WT_BASE=origin/this wt feature-a
WT_SKIP_HOOK=1 wt feature-a
WT_COPY_ENV=false wt feature-a

Use with AI agents

Agents should use deterministic commands. Avoid --shell; use the printed path instead.

wt --json --no-install feature-a
wt --json --no-install --no-env --cwd /path/to/repo feature-a

--json prints one object on stdout, for example { "path": "...", "branch": "feature-a", "base": "origin/main", "envCopied": 3 }.

Agent skill

skills/wt/SKILL.md teaches coding agents these rules. It follows the Agent Skills specification. The skill only gives instructions, so install the wt command too.

The first command uses the skills CLI. The second installs this repo as a Pi package.

Roadmap

1. Add wt repair for moved worktrees. Git has git worktree repair for this.
2. Add shell completions for bash, zsh, and fish.
3. Remove locked worktrees. git worktree remove needs --force twice for them, and wt --force passes it once.

Development

npm install          # dev tools
npm link             # use this checkout as the global wt
npm run format:check
npm run lint
npm test
npm pack --dry-run   # preview the published files

Release

.github/workflows/publish.yml publishes to npm when you push a v* tag. It uses trusted publishing, so no npm token is stored in GitHub, and npm adds provenance for this public repo.

One-time setup:

1. Publish the first version by hand. The trusted publisher is set on the package settings page, so the package must exist: npm login, then npm publish. publishConfig.access makes the scoped package public.
2. On npmjs.com, open the package, then Settings -> Trusted Publisher. Pick GitHub Actions, user gitsoufiane, repo wt, workflow publish.yml.
3. Push the next tag within 2 days. npm expires a trusted publisher that has not published within 2 days of its creation.

Each release:

npm version patch   # or minor / major; commits and tags vX.Y.Z
git push --follow-tags

License

MIT