Issue

The documentation should clearly warn users that git is designed as a single-process tool and running concurrent git operations across multiple worktrees can cause corruption, even though worktrees themselves are safe.

Current Gap

Users may assume that because git worktrees allow multiple branches to be checked out simultaneously, it's safe to run git operations in parallel. This is not the case.

Critical Information to Document

Git's Single-Process Design

Git client is meant to be run by a single process, not multiple processes at the same time, as it could lead to file/data corruption in the .git folder.

While worktrees prevent branch-level corruption (ensuring a branch is checked out in only one worktree), they do not prevent corruption from simultaneous git commands accessing the shared repository data.

What's Shared vs. Isolated

Shared Across All Worktrees:

• .git/objects/ - Object database
• .git/refs/ - References
• .git/config - Configuration
• .git/hooks/ - Hooks
• Git garbage collection
• Pack files

Isolated Per Worktree:

• Working directory files
• .git/HEAD - Current branch pointer
• .git/index - Staging area
• .git/logs/ - Worktree-specific logs

Unsafe Patterns

# ❌ UNSAFE: Concurrent operations
cd worktree1 && git commit -m "change" &
cd worktree2 && git commit -m "change" &
cd worktree3 && git rebase main &

# ❌ UNSAFE: Multiple AI agents running git commands simultaneously
# Each agent in different worktree, all modifying branches concurrently

# ❌ UNSAFE: Background git operations + manual commands
# Claude Code running background git status while you run git rebase

Safe Patterns

# ✅ SAFE: Sequential operations
cd worktree1 && git commit -m "change"
cd worktree2 && git commit -m "change"
cd worktree3 && git rebase main

# ✅ SAFE: Using auto-worktree to coordinate operations
auto-worktree exec --sequential worktree1 worktree2 worktree3 -- git commit -m "change"

Documentation Locations

README.md

Add a prominent "⚠️ Safety Warning" section explaining concurrent operation risks.

docs/BEST_PRACTICES.md

Create detailed guide on:

• Safe parallel development patterns
• How to coordinate multiple AI agents
• When operations are safe vs. unsafe
• Common pitfalls and corruption scenarios

docs/AI_AGENTS.md

Specific guidance for using auto-worktree with Claude Code, Cursor, and other AI tools:

• Disabling background git operations
• Coordinating agent activities
• Safe rebase strategies with multiple agents

CLI Help Text

Add warnings to relevant commands:

$ auto-worktree rebase --help
...
WARNING: Git is not designed for concurrent operations. If you have
multiple agents or processes running in other worktrees, they should
be paused before rebasing to prevent corruption.

Related Issues

• Bug: Git corruption from concurrent access needs better detection and prevention #174 - Git corruption from concurrent access
• Bug: Worktree directories disappear during concurrent AI agent operations #168 - Worktree directories disappear
• Bug: Terminal running AI agents exits unexpectedly without warning #170 - Terminal crashes
• Bug: Claude Code stale lock files interfere with auto-worktree operations #175 - Claude Code lock file conflicts

Resources to Reference

• Parallel worktree workflows: https://medium.com/@dtunai/mastering-git-worktrees-with-claude-code-for-parallel-development-workflow-41dc91e645fe
• Git worktree documentation: https://git-scm.com/docs/git-worktree
• Concurrent development guide: https://www.kenmuse.com/blog/using-git-worktrees-for-concurrent-development/