Git Worktrees

Use grepai seamlessly across git worktrees

Git Worktree Support

grepai automatically detects git worktrees and provides zero-config setup for linked worktrees. If you work on multiple branches in parallel using git worktree add, grepai handles everything transparently.

How It Works

When you run any grepai command (search, trace, watch) from a linked worktree, grepai:

1. Detects that you’re in a linked worktree (not the main repository)
2. Locates the main worktree’s .grepai/ directory
3. Auto-initializes a local .grepai/ by copying config.yaml, index.gob, and symbols.gob from the main worktree
4. Adds .grepai/ to the worktree’s .gitignore

This means search and trace work immediately in any worktree, without re-indexing.

Auto-initialization holds the linked worktree’s .grepai/writer.lock for the complete seed copy. index.gob and symbols.gob finish copying before config.yaml is installed as the completion marker. Concurrent initializers serialize on that lock, and a watcher cannot load a partially copied seed. Each file is written to a synced temporary file and atomically published. If any copy stage fails, all destinations from that attempt are removed and a later discovery pass can retry. Only a successfully parsed config.yaml is treated as the completion marker; a directory containing only writer.lock or partial files is not considered initialized.

Quick Start

# Your main project already has grepai set up
cd /path/to/my-project
grepai watch  # index is built here

# Create a linked worktree for a feature branch
git worktree add ../my-project-feature feature-branch

# grepai works immediately in the linked worktree
cd ../my-project-feature
grepai search "authentication flow"   # uses copied index
grepai trace callers "HandleRequest"   # uses copied symbols

No grepai init or grepai watch required in the linked worktree — it just works.

Explicit Initialization with --inherit

If you prefer to explicitly initialize a worktree (or want to customize the config afterwards), use the --inherit flag:

cd /path/to/my-worktree
grepai init --inherit

This will:

• Detect the main worktree automatically
• Copy its configuration
• Display backend information
• Let you proceed to grepai watch for incremental updates

You can also combine it with --yes for fully non-interactive setup:

grepai init --inherit --yes

Backend Behavior

Each worktree gets its own .grepai/ directory for isolation. The behavior differs depending on your storage backend:

For teams using multiple worktrees, PostgreSQL or Qdrant backends are recommended for shared indexing.

Worktree Identification

Each repository is identified by a stable Worktree ID: a 12-character hex string derived from the SHA-256 hash of the git common directory. This ID is the same for the main worktree and all linked worktrees of the same repository.

grepai init --inherit
# Output:
# Git worktree detected.
#   Main worktree: /path/to/main-repo
#   Worktree ID:   0adda787cae4
#   Backend:       gob

Running grepai watch in a Worktree

After auto-init, you can optionally run grepai watch in the linked worktree to get incremental updates for worktree-specific changes:

cd /path/to/my-worktree
grepai watch

This re-indexes only the files that differ from the copied seed index, keeping your worktree’s index up to date.

What Gets Copied

If config.yaml is missing from the main worktree, auto-init will not proceed.

Disabling Worktree Discovery

By default, grepai watch in the main worktree discovers all linked worktrees, auto-initializes them, and watches them alongside the main project. If you use many short-lived worktrees (e.g. AI-agent sessions) this multiplies indexing work and memory. Opt out in the main worktree’s .grepai/config.yaml:

watch:
  discover_worktrees: false

The option is re-read on every discovery pass, so toggling it takes effect within seconds — no watcher restart needed. Worktrees already being watched are released on the next pass. The key is only consulted in the main worktree’s config; setting it inside a linked worktree’s copy has no effect. If the config can’t be parsed, discovery is skipped for that pass (fail closed) and a warning is logged.

Troubleshooting