A Node.js port of the Ruby worktree_manager gem. wm2 provides a simple and intuitive interface for creating, managing, and removing Git worktrees with built-in hook support.
- Easy worktree management: Create, list, and remove Git worktrees
- Branch operations: Create new branches or checkout existing ones
- Hook system: Execute custom scripts before/after worktree operations
- Conflict detection: Automatic validation to prevent path and branch conflicts
- CLI interface: Simple command-line tool for quick operations
- Configuration initialization: Easy setup with
wm2 initcommand - Branch reset: Reset worktree branches to origin/main with
wm2 reset - Interactive mode: Jump between worktrees and remove with interactive selection
- Cross-platform: Works on macOS, Linux, and Windows
Install wm2 globally using npm:
npm install -g wm2
Or using yarn:
yarn global add wm2
wm2 provides a CLI tool for managing worktrees:
# Show version wm2 version # Initialize configuration file wm2 init # List all worktrees wm2 list # Create a new worktree using just a name (uses worktrees_dir) wm2 add feature-branch # Create a worktree with a relative path wm2 add ../feature-branch # Create a worktree with an absolute path wm2 add /path/to/feature-branch # Create a worktree with an existing branch wm2 add feature-branch existing-branch # Create a worktree with a new branch wm2 add feature-branch -b new-feature-branch # Remove a worktree using just a name wm2 remove feature-branch # Remove a worktree with a path wm2 remove ../feature-branch # Remove all worktrees (interactive confirmation) wm2 remove --all # Force operations (bypass safety checks) wm2 add existing-dir -f wm2 remove worktree-with-changes -f # Track remote branches wm2 add pr-154 -t origin/pr-154 # Create local pr-154 tracking origin/pr-154 wm2 add pr-154 origin/pr-154 # Auto-detect remote branch wm2 add hotfix -t upstream/hotfix-123 # Track from different remote # Reset worktree branch to origin/main (must be run from worktree) wm2 reset # Reset current branch to origin/main wm2 reset -f # Force reset (discard uncommitted changes) # Jump between worktrees (interactive) wm2 jump # Remove worktrees interactively wm2 remove # Get help for any command wm2 --help # Show all commands wm2 add --help # Show help for add command wm2 remove -h # Short help flag also works
wm2 makes it easy to work with remote branches:
# Method 1: Using --track (-t) option wm2 add pr-154 -t origin/pr-154 # This will: # 1. Fetch origin/pr-154 # 2. Create a new local branch 'pr-154' tracking 'origin/pr-154' # 3. Create worktree at '../worktrees/pr-154' (or configured location) # Method 2: Auto-detection wm2 add pr-154 origin/pr-154 # If the second argument contains '/', it's treated as a remote branch # Creates local 'pr-154' tracking 'origin/pr-154' # Different remote names wm2 add hotfix -t upstream/hotfix-123 # Track from 'upstream' remote wm2 add feature -t fork/feature # Track from 'fork' remote
wm2 provides interactive commands for better user experience:
# Jump between worktrees interactively wm2 jump # Shows a list of all worktrees with their branches # Select one to jump to it # Remove worktrees interactively wm2 remove # Shows a list of worktrees # Select one or more to remove # Confirms before removing # Remove all worktrees with confirmation wm2 remove --all # Lists all worktrees that will be removed # Asks for confirmation # Option to force remove if some have uncommitted changes
After running wm2 init, a .worktree.yml file is created in your repository root:
worktrees_dir: ../worktrees
This specifies the default directory where worktrees will be created when using just a name.
wm2 supports hooks for custom automation. Hooks are defined in .worktree.yml:
worktrees_dir: ../worktrees # Simple string command pre_add: echo "Creating worktree..." post_add: echo "Worktree created!" # Array of commands pre_remove: - echo "Removing worktree..." - ./scripts/cleanup.sh # Advanced configuration with options hooks: post_add: commands: - npm install - npm run build pwd: $WORKTREE_ABSOLUTE_PATH stop_on_error: true
Available hooks:
pre_add: Run before creating a worktreepost_add: Run after creating a worktreepre_remove: Run before removing a worktreepost_remove: Run after removing a worktree
Environment variables available in hooks:
WORKTREE_BRANCH: Branch nameWORKTREE_PATH: Relative path to worktreeWORKTREE_ABSOLUTE_PATH: Absolute path to worktreeWORKTREE_MAIN: Path to main repositoryWORKTREE_MANAGER_ROOT: Repository root directory
You can also use wm2 programmatically in your Node.js applications:
import { Manager, ConfigManager } from 'wm2'; // Initialize manager const manager = new Manager('/path/to/repo'); // List worktrees const worktrees = await manager.list(); console.log(worktrees); // Add a worktree await manager.add('/path/to/new-worktree', { branch: 'feature-branch' }); // Remove a worktree await manager.remove('/path/to/worktree'); // Work with configuration const config = new ConfigManager('/path/to/repo'); const worktreesDir = config.getWorktreesDir();
- Node.js 22.17.1 or higher
- Git 2.5.0 or higher (for worktree support)
# Clone the repository git clone https://github.com/nacyot/wm2.git cd wm2 # Install dependencies npm install # Run tests npm test # Run linter npm run lint # Build the project npm run build
This project is licensed under the MIT License - see the LICENSE file for details.
wm2 is a Node.js port of the Ruby worktree_manager gem.