iso

Isolated worktree manager for Git repositories

iso is a command-line tool that simplifies the creation and management of Git worktrees, enabling you to work in clean, isolated environments without affecting your main repository checkout.

Table of Contents

• Overview
• Why iso?
• Features
• Installation
• Quick Start
• Commands
• Examples
• How It Works
• Requirements
• License

Overview

iso makes it easy to create temporary, isolated Git worktrees for running commands, testing changes, or working with AI coding assistants like Claude. Instead of stashing changes, switching branches, or cloning your repository multiple times, iso creates lightweight worktrees that share the same Git history.

Why iso?

Problem: You want to run a command in a clean checkout of your repository, but you have uncommitted changes in your working directory.

Traditional Solutions:

• Stash changes, run command, unstash (tedious)
• Clone the repository again (wasteful of disk space)
• Manually create and manage Git worktrees (complex)

iso Solution: One command creates an isolated worktree, runs your command, and drops you into a shell—all without touching your main working directory.

Features

• One-Command Worktree Creation: Create and enter a worktree with a single command
• Smart Branch Detection: Automatically detects your repository's default branch (main/master)
• Named Worktrees: Create reusable worktrees with custom names
• Command Execution: Run commands in the worktree before entering an interactive shell
• Worktree Management: List, switch between, and clean up worktrees easily
• Safe Operations: Warns about nested worktrees and requires confirmation for destructive actions
• Zero Dependencies: Pure Python with no external packages required
• Shell Integration: Opens your preferred shell ($SHELL) in the worktree

Installation

From Source

# Clone the repository
git clone https://github.com/efloss/iso.git
cd iso

# Make the script executable
chmod +x iso

# Add to your PATH (optional)
sudo ln -s "$(pwd)/iso" /usr/local/bin/iso

Or add the directory to your PATH:

export PATH="$PATH:/path/to/iso"

Quick Start

# Create a worktree and start an interactive shell
iso run

# Create a worktree, run a command, then start a shell
iso run make test

# Create a named worktree for a feature
iso run -b feature-authentication

# List all worktrees
iso list

# Switch to an existing worktree
iso switch

# Return to the main repository
iso main

# Clean up all worktrees
iso cleanup

Commands

iso run [OPTIONS] [COMMAND]

Create a new worktree and optionally run a command in it.

Options:

• -b, --branch BRANCH - Custom name for the worktree directory and branch (sanitized automatically)
• --base-dir DIR - Directory where worktree will be created (default: parent directory of repository)
• --no-shell - Don't start an interactive shell after command execution

Arguments:

• COMMAND - Optional command to execute in the worktree

Examples:

iso run                          # Create anonymous worktree
iso run -b fix-bug-123          # Create named worktree
iso run npm test                # Create worktree and run tests
iso run --no-shell npm build    # Run build without interactive shell

iso list

List all worktrees with their paths, branches, and commit SHAs.

Example output:

Worktrees:
  /path/to/myproject (main) - abc1234
  /path/to/myproject-wt-feature-auth (feature-auth) - def5678
  /path/to/myproject-wt-20250111-143022 (iso/20250111-143022) - abc1234

iso switch [TARGET]

Switch to an existing worktree.

• Without TARGET: Shows an interactive menu to select a worktree
• With TARGET: Switches to the worktree matching the name or path

Examples:

iso switch                    # Interactive selection
iso switch feature-auth       # Switch by name
iso switch /path/to/worktree  # Switch by path

iso main

Return to the main repository checkout from a worktree. Opens an interactive shell in the main repository directory.

iso cleanup [OPTIONS]

Remove all non-main worktrees.

Options:

• -y, --yes - Skip confirmation prompt

Examples:

iso cleanup      # Prompt for confirmation
iso cleanup -y   # Skip confirmation

Examples

Working with AI Coding Assistants

Run Claude in a clean worktree without affecting your current work:

iso run claude

Working on Multiple Features

Create separate worktrees for different features:

iso run -b feature-login
# Work on login feature...
iso main

iso run -b feature-api
# Work on API feature...

Quick Code Review

Create a temporary worktree to review changes:

iso run -b review-pr-123 --no-shell gh pr checkout 123 && git diff main

CI/CD Simulation

Run your CI pipeline in a clean environment:

iso run --no-shell ./scripts/ci-build.sh

How It Works

1. Worktree Creation: iso uses Git's worktree feature to create a new working directory linked to your repository
2. Default Branch: Detects your repository's default branch (main/master) using Git remote information
3. Naming Convention:
   • Named: {repo-name}-wt-{branch-name}
   • Anonymous: {repo-name}-wt-{timestamp}
4. Command Execution: Runs your command in the worktree directory
5. Shell Integration: Opens your preferred shell ($SHELL or /bin/bash) in the worktree

All worktrees share the same Git object database, making them lightweight and fast to create.

Worktree Location

By default, worktrees are created in the parent directory of your repository:

/path/to/projects/
├── myproject/              # Main repository
├── myproject-wt-feature/   # Named worktree
└── myproject-wt-20250111/  # Anonymous worktree

You can customize this with --base-dir:

iso run --base-dir /tmp -b temp-work

Requirements

• Python: 3.10 or higher
• Git: Any recent version with worktree support
• Operating System: Linux, macOS, or WSL

No external Python packages required—iso uses only the standard library.

License

MIT License - feel free to use, modify, and distribute as needed.

---

Tips:

• Use named worktrees (-b) for long-running work
• Use anonymous worktrees for quick, disposable tasks
• Run iso cleanup periodically to remove unused worktrees
• The worktree path is printed to stdout, enabling wrapper scripts

Contributing:

Issues and pull requests are welcome! Please ensure the code follows the existing style and includes appropriate error handling.