How to Use Git Worktrees with Gemini CLI

Git worktrees allow you to work on multiple branches simultaneously by checking out different branches into separate directories. This guide explains how to use Gemini CLI effectively with Git worktrees, including important limitations and practical workarounds.

Known Limitations (Important)

Before setting up Git worktrees with Gemini CLI, be aware of these significant limitations:

Tool Path Restrictions (Issue #12050) Gemini CLI tools are restricted to the primary workspace and cannot access files in worktree paths. This means file operations, code analysis, and other tool-based features may not work correctly when operating on worktree directories from the main repository.

Symlinks Not Followed (Issue #11547) Gemini CLI never follows symbolic links for security reasons. You cannot symlink your GEMINI.md or other configuration files - they must be copied.

GEMINI.md Detection Issues Git worktrees contain a .git FILE (pointing to the main repository) rather than a .git FOLDER. This can cause issues with GEMINI.md detection in some cases.

Race Condition Risk Running multiple Gemini CLI processes that access the same .git folder simultaneously can risk repository corruption in edge cases.

Prerequisites

Before you begin, ensure you have:

• Git version 2.5 or higher (worktrees introduced in 2.5)
• Gemini CLI installed (installation guide)
• An existing Git repository to work with
• Basic familiarity with Git branching

To check your Git version:

git --version

Understanding Git Worktrees

A Git worktree is an additional working directory linked to your repository. Each worktree can have a different branch checked out, allowing you to:

• Work on multiple features simultaneously
• Compare code across branches side-by-side
• Run tests on one branch while developing on another
• Keep a stable branch available while experimenting

my-project/                    # Main repository (main branch)
├── .git/                      # Git data (shared by all worktrees)
├── GEMINI.md
└── src/

my-project-feature/            # Worktree (feature branch)
├── .git                       # FILE pointing to main .git folder
├── GEMINI.md                  # Must be COPIED, not symlinked
└── src/

Step-by-Step Setup

macOS and Linux

Step 1: Create a Git Worktree

From your main repository directory:

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

# Or create a worktree with a new branch
git worktree add -b new-feature ../my-project-new-feature main

Step 2: Copy GEMINI.md to the Worktree

Do NOT symlink - Gemini CLI will not follow symlinks:

# Copy your configuration file
cp GEMINI.md ../my-project-feature/

# If you have other Gemini configuration, copy that too
cp -r .gemini/ ../my-project-feature/ 2>/dev/null || true

Step 3: Launch Gemini CLI from Within the Worktree

This is the critical workaround for the tool path restriction:

# Navigate to the worktree directory
cd ../my-project-feature

# Launch Gemini CLI from within the worktree
gemini

Each worktree needs its own Gemini CLI instance launched from within that directory.

Step 4: Verify the Setup

Test that Gemini CLI recognizes the worktree as a project:

# From within the worktree
gemini "list the files in this directory"

Windows

Step 1: Create a Git Worktree

Open PowerShell and navigate to your repository:

# Create a worktree for an existing branch
git worktree add ..\my-project-feature feature-branch

# Or create a worktree with a new branch
git worktree add -b new-feature ..\my-project-new-feature main

Step 2: Copy GEMINI.md to the Worktree

# Copy your configuration file
Copy-Item GEMINI.md -Destination ..\my-project-feature\

# If you have other Gemini configuration, copy that too
Copy-Item -Recurse .gemini -Destination ..\my-project-feature\ -ErrorAction SilentlyContinue

Step 3: Launch Gemini CLI from Within the Worktree

# Navigate to the worktree directory
cd ..\my-project-feature

# Launch Gemini CLI from within the worktree
gemini

Step 4: Verify the Setup

gemini "list the files in this directory"

Session Management

Gemini CLI stores sessions in ~/.gemini/tmp/<project_hash>/chats/. Each project (including worktrees) gets a unique hash based on its path, so sessions are project-specific.

Understanding Session Storage

~/.gemini/
└── tmp/
    ├── abc123/              # Main repository sessions
    │   └── chats/
    │       └── session1.json
    └── def456/              # Worktree sessions
        └── chats/
            └── session1.json

Managing Multiple Sessions

When working with multiple worktrees, consider using a terminal multiplexer or multiple terminal windows:

Using tmux (macOS/Linux):

# Create a tmux session with panes for each worktree
tmux new-session -s dev

# Split horizontally
tmux split-window -h

# In first pane: main repository
cd ~/projects/my-project && gemini

# In second pane: worktree
cd ~/projects/my-project-feature && gemini

Using Windows Terminal:

1. Open Windows Terminal
2. Click the dropdown arrow and select "Split pane"
3. Navigate to different worktrees in each pane
4. Launch Gemini CLI in each pane

CCManager for Multi-Session Management

For complex multi-worktree workflows, consider using a session manager tool like CCManager (if available) to coordinate between multiple Gemini CLI instances.

Workarounds for Limitations

Workaround 1: Launch from Within Each Worktree

The primary workaround for tool path restrictions is simple but essential:

Always launch Gemini CLI from within the worktree directory, not from the main repository.

# Wrong - tools won't work on worktree files
cd ~/projects/main-repo
gemini "analyze code in ../my-project-feature/src"

# Correct - tools work on local files
cd ~/projects/my-project-feature
gemini "analyze code in ./src"

Workaround 2: Keep Configuration in Sync

Create a script to sync GEMINI.md across worktrees:

#!/bin/bash
# sync-gemini-config.sh

MAIN_REPO="$HOME/projects/my-project"
GEMINI_MD="$MAIN_REPO/GEMINI.md"

# Get list of worktrees
for worktree in $(git -C "$MAIN_REPO" worktree list --porcelain | grep "worktree" | cut -d' ' -f2); do
    if [ "$worktree" != "$MAIN_REPO" ]; then
        cp "$GEMINI_MD" "$worktree/"
        echo "Synced GEMINI.md to $worktree"
    fi
done

Workaround 3: Use Separate Terminal Windows

For the safest workflow that avoids any race conditions:

1. Use one terminal window per worktree
2. Launch Gemini CLI in each window from within that worktree
3. Avoid running concurrent operations that modify the same files

Best Practices

Do

• Launch Gemini CLI from within each worktree - This is the key to making tools work
• Copy GEMINI.md to each worktree - Never symlink configuration files
• Use separate terminal windows - One Gemini instance per worktree
• Keep worktrees on different branches - Avoids Git conflicts
• Regularly sync configuration changes - Use the sync script above

Avoid

• Running Gemini from main repo on worktree paths - Tools will fail
• Using symlinks for configuration - Gemini won't follow them
• Running multiple Gemini instances on the same worktree - Risk of conflicts
• Concurrent Git operations across Gemini instances - Risk of repository corruption

Recommended Workflow

1. Create your worktrees for different features or branches
2. Copy GEMINI.md to each worktree
3. Open a dedicated terminal for each worktree
4. Launch Gemini CLI from within each worktree directory
5. Work on each feature independently

Managing Worktrees

List All Worktrees

git worktree list

Remove a Worktree

# Remove the worktree directory
git worktree remove ../my-project-feature

# Or force remove if there are changes
git worktree remove --force ../my-project-feature

Prune Stale Worktrees

git worktree prune

Troubleshooting

Tools Not Working on Worktree Files

Symptom: Gemini CLI cannot read, write, or analyze files in the worktree.

Solution: You likely launched Gemini from the main repository. Exit and relaunch from within the worktree:

cd /path/to/worktree
gemini

GEMINI.md Not Detected

Symptom: Gemini CLI doesn't seem to use your project configuration.

Solutions:

1. Verify GEMINI.md exists in the worktree (not symlinked)
2. Check the file has the correct name (case-sensitive)
3. Try creating a fresh GEMINI.md in the worktree

Session Data Not Persisting

Symptom: Chat history seems lost between sessions.

Solution: This is expected behavior - each worktree path gets a unique session hash. Sessions are intentionally separate per project path.

Git Corruption Warnings

Symptom: Git reports index lock or corruption errors.

Solutions:

1. Ensure only one Gemini instance runs per worktree
2. Avoid concurrent Git operations across instances
3. If corruption occurs, you may need to run git fsck or restore from backup

Additional Resources

• Git Worktrees Documentation
• Gemini CLI GitHub Repository
• How to Install Google Gemini CLI
• How to Configure MCP Integrations

Need help optimizing your development workflow? Inventive HQ specializes in developer productivity tools and AI-assisted development practices. Contact us for a consultation on integrating AI tools into your team's workflow.