git-worktree-utils

A safe git worktree management CLI with automatic environment file syncing.

Features

• Safety checks - Blocks operations with uncommitted changes or unpushed commits
• Branch protection - Warns if a branch is already checked out elsewhere
• Main repo protection - Prevents accidental operations on the main repository
• Automatic .env copying - Copies all .env* files when creating new worktrees
• Environment syncing - Sync .env files across worktrees with one command
• Fuzzy search - Find worktrees by partial name match

Installation

npm install -g git-worktree-utils

Usage

Unified CLI

wt <command> [options]

Individual Commands

wt-add [options]
wt-list
wt-find [options]
wt-rename [options]
wt-remove [options]
wt-switch [options]
wt-sync-env [options]

Help

wt help                  # general help — lists all commands
wt help <command>        # detailed help for one command
wt <command> --help      # same as above (also: -h)
wt-<command> --help      # works on individual binaries too

Commands

wt add - Create a new worktree

Creates a new git worktree and automatically copies all .env* files from project directories.

wt add --dirName=my-feature --branchName=feature/my-feature
wt add --dirName=bugfix-123  # uses dirName as branch name

Options:

• --dirName=<name> - Directory name for the worktree (required)
• --branchName=<name> - Branch name (defaults to dirName)

wt list (alias: wt ls)

Lists all git worktrees with status markers.

wt list
wt list --sort     # main first, then clean worktrees, then ones with markers
wt list --plain    # raw `git worktree list` output (no markers)

Status markers:

• [main] — the main repository (cannot be switched/renamed/removed)
• [dirty:N] — N files with uncommitted changes
• [unpushed:N] — N local commits not present on any remote
• [no-upstream] — branch has no upstream tracking ref

When any worktree has [dirty:N] or [unpushed:N], the output ends with copy-pasteable git -C commands to inspect the actual files/commits.

wt find (alias: wt search)

Search worktrees by partial name match (case-insensitive).

wt find --search=feature
wt find --search=FS-1234

wt rename (alias: wt mv)

Rename a worktree directory with safety checks.

wt rename --oldDirName=old-name --newDirName=new-name

Safety checks:

• Blocks if uncommitted changes exist
• Blocks if unpushed commits exist
• Prevents renaming the main repository

wt remove (alias: wt rm)

Remove a worktree with safety checks.

wt remove --dirName=old-feature

Safety checks:

• Blocks if uncommitted changes exist
• Blocks if unpushed commits exist
• Prevents removing the main repository

wt switch (alias: wt co, wt checkout)

Repoint an existing worktree at a different branch: renames the worktree directory, checks out the new branch, and re-copies .env* files.

wt switch --fromDirName=old-feature --branchName=feature/new
wt switch --fromDirName=old-feature --branchName=feature/new --toDirName=custom-dir

Options:

• --fromDirName=<name> - Existing worktree directory (required)
• --branchName=<name> - Branch to switch to (required; created if it doesn't exist)
• --toDirName=<name> - New directory name (defaults to branchName)

Safety checks:

• Blocks if uncommitted changes exist
• Blocks if unpushed commits exist
• Prevents switching the main repository
• Blocks if target branch is checked out in another worktree

wt sync-env (alias: wt sync)

Sync .env* files from current worktree to other worktrees.

wt sync-env --to=other-worktree  # sync to specific worktree
wt sync-env --all                 # sync to ALL other worktrees

How .env Copying Works

When creating a worktree or syncing, the tool:

1. Finds all directories containing package.json or project.json (excluding node_modules)
2. Copies all .env* files (.env, .env.local, .env.development, etc.) to the same relative path in the target worktree

This is especially useful for monorepos where environment files are scattered across multiple projects.

Examples

Typical Workflow

# Create a new feature worktree
wt add --dirName=my-feature --branchName=feature/awesome

# ... work on the feature, add new .env variables ...

# Sync your .env changes to all other worktrees
wt sync-env --all

# Find a specific worktree
wt find --search=awesome

# Clean up when done
wt remove --dirName=my-feature

Use with npm scripts

Add to your package.json:

{
  "scripts": {
    "wt:add": "wt add",
    "wt:list": "wt list",
    "wt:sync": "wt sync-env --all"
  }
}

License

MIT

Author

Avi Weiss