wtman

wtman is a CLI tool for managing Git worktrees more conveniently.

It automates worktree path naming using templates and executes routine tasks like npm install or copying .env files through hooks. With separate team and user configurations that merge automatically, it's easy to adopt in any project.

Features

• Template-based path generation - Automatically determine worktree paths from branch names
• Hook automation - Execute commands and file operations when creating or removing worktrees
• Three-layer configuration merge - Automatically merge team, user, and worktree-specific settings
• Metadata management - Attach descriptions and tags to worktrees

Installation

npm install -g wtman

Quick Start

# Create a worktree
wtman add feature/awesome-feature

# Create with description and tags
wtman add feature/auth --desc "Implement authentication" --tag feature,wip

# List worktrees
wtman list

# Remove a worktree (interactive selection)
wtman remove

Commands

wtman add <branch>

Create a new worktree.

wtman add <branch> [--desc <description>] [--tag <tags>]

Option	Description
--desc	Set a description for the worktree
--tag	Set tags (comma-separated)

Workflow:

1. Load configuration and generate path from worktree.template
2. Execute pre-worktree-add hooks
3. Create worktree with git worktree add
4. Execute post-worktree-add hooks
5. Save metadata

wtman remove

Remove a worktree. Running without arguments opens interactive selection.

wtman remove [-b <branch>] [-w <path>] [--force] [--delete-branch|--keep-branch]

Option	Description
-b	Specify by branch name
-w	Specify by path
--force	Skip confirmation and force removal
--delete-branch	Also delete the branch
--keep-branch	Keep the branch

Safety features:

• Warns if there are uncommitted changes
• Warns if there are commits not pushed to remote

wtman list

Display a list of worktrees.

wtman list [-f <format>]

Option	Value	Description
-f	table	Table format (default)
	json	JSON format
	tsv	Tab-separated format

Configuration

Configuration is written in YAML format. There are three levels of configuration files that merge automatically.

Configuration Files

File	Purpose	Git-tracked
.wtman/config.yaml	Team shared settings	Yes
.wtman/config.user.yaml	User-specific settings	No
.wtman/config.user.worktree.yaml	Worktree-specific settings	No

Merge order: Team → User → Worktree (later settings take precedence)

Note: It's recommended to add config.user.*.yaml to .gitignore

Configuration Schema

worktree:
  template: "../${{ original.basename }}-${{ worktree.branch }}"  # Path template
  separator: hyphen       # hyphen | underscore | slash
  deleteBranch: ask       # ask | always | never

pre-worktree-add: []      # Hooks before worktree creation
post-worktree-add: []     # Hooks after worktree creation
pre-worktree-remove: []   # Hooks before worktree removal
post-worktree-remove: []  # Hooks after worktree removal

Configuration Example

# .wtman/config.yaml
worktree:
  template: "../${{ original.basename }}-${{ worktree.branch }}"
  separator: hyphen

post-worktree-add:
  - name: Install dependencies
    run: npm install

  - name: Copy environment file
    copy: .env.example

  - name: Link node_modules
    link: node_modules

Hooks

You can define processes that automatically execute when creating or removing worktrees.

Phases

Phase	Timing	Default Working Directory
pre-worktree-add	Before creation	Main tree
post-worktree-add	After creation	Worktree
pre-worktree-remove	Before removal	Worktree
post-worktree-remove	After removal	Main tree

Actions

run - Execute shell command

post-worktree-add:
  - name: Install dependencies
    run: npm install

copy - Copy files/directories

Copy files from the main tree to the worktree.

post-worktree-add:
  - name: Copy config files
    copy:
      - .env.example
      - config/local/

link - Create symbolic links

Create symbolic links in the worktree pointing to the main tree.

post-worktree-add:
  - name: Link shared directories
    link:
      - node_modules
      - .cache

mkdir - Create directories

post-worktree-add:
  - name: Create directories
    mkdir:
      - logs
      - tmp

remove - Remove files/directories

pre-worktree-remove:
  - name: Clean up
    remove:
      - .env.local
      - logs/

Specifying Working Directory

Use the working-directory option to change the working directory.

post-worktree-add:
  - name: Install frontend dependencies
    working-directory: frontend
    run: npm install

Template Variables

You can embed variables using the ${{ variable.name }} format.

Available Variables

Variable	Description	Example
${{ original.path }}	Absolute path of main tree	/home/user/project
${{ original.basename }}	Directory name of main tree	project
${{ worktree.path }}	Absolute path of worktree	/home/user/project-feature
${{ worktree.basename }}	Directory name of worktree	project-feature
${{ worktree.branch }}	Branch name	feature-auth

Note: worktree.path and worktree.basename are only available in post-worktree-add and pre-worktree-remove

Branch Name Conversion (separator)

Use worktree.separator to convert / in branch names.

separator	Input	Output
hyphen	feature/auth	feature-auth
underscore	feature/auth	feature_auth
slash	feature/auth	feature/auth

Metadata

You can attach descriptions and tags to worktrees. They are stored in .wtman/worktrees.yaml.

# Set when adding
wtman add feature/auth --desc "Authentication feature" --tag feature,high-priority

# View in list
wtman list