Create Worktree

A CLI tool to create git worktrees using bare repositories, enabling efficient parallel development workflows.

English | 中文

Features

• Creates bare repositories for efficient git worktree management
• Sets up .git file pointing to the bare repository
• Configures the bare repository for proper remote branch tracking
• Enables parallel feature development with isolated environments

Quick Start

There are two ways to use create-worktree:

1. Install globally

npm i -g create-worktree
# then use as a git subcommand:
git create-worktree <repo-url>
# or the short alias:
git cwt <repo-url>

2. Use without installing (current method)

# Initialize worktree structure
npm create worktree https://github.com/user/repo.git

# Create main worktree
git worktree add main

# Create feature branch worktree
git worktree add -b "feature-auth" feature-auth

What it does

1. Creates a bare repository: Clones the repository as a bare repo into a .bare subfolder
2. Creates a .git file: Points to the bare repository with gitdir: ./.bare
3. Updates .bare/config: Ensures proper remote branch tracking configuration

Worktree Development Pattern

Traditional Development vs Worktree Pattern

Traditional Development:

• Single working directory
• Context switching between branches is slow
• Risk of uncommitted changes blocking branch switches
• Difficult to work on multiple features simultaneously

Worktree Pattern:

• Multiple independent working directories
• Each branch has its own isolated environment
• Zero context switching overhead
• Perfect for parallel development

Setting Up Your Workflow

# 1. Initialize the worktree structure
npm create worktree https://github.com/your-org/your-project.git

# 2. Create main branch worktree
git worktree add main

# 3. Create feature worktrees
git worktree add -b "feature-user-auth" feature-auth
git worktree add -b "feature-payment-gateway" feature-payment
git worktree add -b "bugfix-login-issue" bugfix-login

# 4. Navigate to any worktree
cd feature-auth
# Work on auth feature...

cd ../feature-payment
# Work on payment feature...

Directory Structure

my-project/
├── .bare/           # Bare repository (git history)
├── .git             # Git directory pointer
├── main/            # Main branch worktree
├── feature-auth/    # Auth feature worktree
├── feature-payment/ # Payment feature worktree
└── bugfix-login/    # Bug fix worktree

Benefits for AI-Assisted Programming

1. Parallel AI Development

AI assistants can work on multiple features simultaneously in isolated worktrees:

# AI works on auth feature in one worktree
cd feature-auth
# AI implements authentication logic

# Meanwhile, another AI instance works on payment feature
cd ../feature-payment
# AI implements payment processing

2. Context Isolation

Each worktree provides perfect context isolation:

• AI only sees relevant files for the current feature
• No cross-contamination between different features
• Cleaner AI responses with focused context

3. Safe Experimentation

AI can safely experiment and iterate:

• Risk-free testing of AI-generated code
• Easy rollback if AI suggestions don't work
• Isolated testing environments for each AI task

4. Concurrent Development

Multiple AI instances can work concurrently:

# Terminal 1: AI working on auth
cd feature-auth
claude "Implement JWT authentication"

# Terminal 2: AI working on payment
cd feature-payment
claude "Implement Stripe integration"

# Terminal 3: AI working on UI
cd feature-ui
claude "Create user dashboard"

5. Efficient Code Review

AI can review changes across worktrees:

# Compare AI-generated changes
git diff main..feature-auth
git diff main..feature-payment

# Merge completed features
git checkout main
git merge feature-auth
git merge feature-payment

Advanced Worktree Management

Listing Worktrees

git worktree list

Cleaning Up Worktrees

# Remove worktree after merging
git worktree remove feature-auth

# Prune stale worktrees
git worktree prune

Moving Worktrees

git worktree move feature-auth features/auth

Best Practices

1. Worktree Naming Convention

feature-<description>    # New features
bugfix-<issue>           # Bug fixes
hotfix-<problem>         # Emergency fixes
experiment-<idea>        # Experimental features

2. Worktree Lifecycle

# Create
git worktree add -b "feature-new-api" feature-api

# Develop
cd feature-api
# Make changes, commit

# Test
# Run tests in isolated environment

# Merge
cd ../main
git merge feature-api

# Cleanup
git worktree remove feature-api
git branch -d feature-api

Troubleshooting

Common Issues

1. Worktree already exists

   git worktree remove <worktree-path>
   git worktree prune

2. Branch already checked out

   git worktree list
   git worktree remove <existing-worktree>

3. Clean up failed worktrees

   git worktree prune

Development

# Install dependencies
bun install

# Build
bun run build

# Run tests
bun run test

# Type check
bun run typecheck

# Lint
bun run lint

Contributing

1. Fork the repository
2. Create a feature worktree: git worktree add -b "feature-your-feature" feature-your-feature
3. Make your changes
4. Run tests and linting
5. Submit a pull request

License

MIT