cowl

Copy-on-write variations for a directory. cowl makes a CoW clone into a global workspace and helps you jump into it and merge changes back.

Install

• Install via npm:

npm install -g @monotykamary/cowl

• Install via bun:

bun install -g @monotykamary/cowl

• Build a standalone binary:

bun run build

The binary is at dist/cowl.

Usage

Create a variation and jump to it:

pushd -- "$(cowl new)"

Or use eval for built-in pushd output:

eval "$(cowl new --cd)"

If you want to jump to an existing variation:

eval "$(cowl cd <name>)"

Shell Integration (Optional)

Install a shell wrapper that makes cowl new run pushd automatically:

cowl install-shell --shell zsh

Then reload your shell config or open a new terminal.

If you want to preview the snippet instead of installing it:

cowl shell --shell zsh

Remove the wrapper:

cowl uninstall-shell --shell zsh

List variations for the current project:

cowl list

Show the project root for the current directory:

cowl root

Inspect a variation:

cowl info <name>

Check a variation's git status:

cowl status <name>

Merge changes back into the current directory (default: cleans up the variation):

cowl merge <name>

Merge into a new branch in the source repo:

cowl merge <name> --branch

Merge into a specific branch name:

cowl merge <name> --branch feature/cowl-merge

Keep the variation after merging:

cowl merge <name> --keep

Dry run merge:

cowl merge <name> --dry-run

Delete a variation:

cowl clean <name>

Behavior

• Variations live in ~/.local/share/cowl/<basename>-<hash>/<variation> (XDG Base Directory compliant).
• cowl new uses the current directory as the source.
• Git merge: if the source directory is a git repo root, merge uses git 3-way apply and syncs untracked files.
• cowl merge --branch creates or switches to cowl/<variation> in the source repo.
• Rsync merge: if git is unavailable, merge uses rsync; deletions are opt-in with --delete.
• Use --no-color or NO_COLOR=1 to disable ANSI formatting.

Context Awareness

When you run commands from within a variation directory, cowl automatically detects this and works with the source directory:

cowl whereami   # Show current context (variation or source)
cowl host       # Print source directory path when in a variation
cowl cd host    # Navigate back to source from a variation
cowl list       # List variations (works from within variation too)

Commands

• cowl new [name] [--cd] - Create a new variation
• cowl cd <name>|host - Navigate to a variation or back to source
• cowl path <name> - Print variation path
• cowl list [--all] - List variations for current project
• cowl root - Show project root directory
• cowl info <name> - Show variation details
• cowl status <name> - Check variation git status
• cowl whereami - Show current context
• cowl host - Print source path (when in variation)
• cowl doctor - Diagnose CoW support and system configuration
• cowl shell [--shell zsh|bash|fish] - Print shell integration snippet
• cowl install-shell [--shell zsh|bash|fish] [--rc path] - Install shell wrapper
• cowl uninstall-shell [--shell zsh|bash|fish] [--rc path] - Remove shell wrapper
• cowl merge <name> [--dry-run] [--keep] [--delete] [--branch [name]] - Merge changes back
• cowl clean <name> - Delete a variation

Known Limitations

Enterprise Security Software (EDR)

Issue: When using cowl on machines with endpoint detection and response (EDR) software like CrowdStrike, cowl new may be significantly slower than expected, even though Copy-on-Write is technically working.

Why: cowl copies the entire directory including all files (e.g., node_modules/, build artifacts), while git worktrees only checkout tracked source files. With 5,000+ files in a typical project:

• Git worktree: ~20 files (source code only)
• cowl variation: ~5,000+ files (including node_modules)

Each file operation triggers EDR scanning hooks. With 10ms scan latency per file:

• Git worktree: 20 × 10ms = 0.2 seconds ✅
• cowl: 5,000 × 10ms = 50+ seconds ❌

Workaround:

• Use git worktrees for quick branches where you don't need full environment isolation
• Use cowl when you need complete isolation (different dependency versions, experimental changes)
• Accept the slower creation time as the cost of complete isolation

Verify CoW is working: Run cowl doctor to test CoW support and see if your system supports it properly.