gemini-cli/docs/cli/git-worktrees.md

Parallel sessions with Git worktrees

When working on multiple tasks at once, you can use Git worktrees to give each Gemini session its own copy of the codebase. Git worktrees create separate working directories that each have their own files and branch while sharing the same repository history. This prevents changes in one session from colliding with another.

Learn more about session management.

Note: This is a preview feature currently under active development. Your feedback is invaluable as we refine this feature. If you have ideas, suggestions, or encounter issues:

• Open an issue on GitHub.
• Use the /bug command within Gemini CLI to file an issue.

Learn more in the official Git worktree documentation.

How to enable Git worktrees

Git worktrees are an experimental feature. You must enable them in your settings using the /settings command or by manually editing your settings.json file.

1. Use the /settings command.
2. Search for and set Enable Git Worktrees to true.

Alternatively, add the following to your settings.json:

{
  "experimental": {
    "worktrees": true
  }
}

How to use Git worktrees

There are two ways to use Git worktrees: at startup or mid-session.

Using the startup flag

Use the --worktree (-w) flag to create an isolated worktree and start Gemini CLI in it.

• Start with a specific name: The value you pass becomes both the directory name (within .gemini/worktrees/) and the branch name.

  gemini --worktree feature-auth
  

• Start with a random name: If you omit the name, Gemini generates a random one automatically (for example, worktree-a1b2c3d4).

  gemini --worktree
  

Using the slash command

If you are already in a Gemini session, you can switch to a new isolated worktree without restarting using the /worktree command.

• Switch with a specific name:

  /worktree feature-auth
  

• Switch with a random name:

  /worktree
  

When you use /worktree, Gemini:

1. Checks your current environment: If you are already in a worktree, it automatically cleans it up if there are no changes, or preserves it if there are.
2. Creates the new worktree: Sets up a fresh copy of the codebase and a new branch.
3. Pivots the session: Switches its working directory and reloads the project context (memory and tools) so you can immediately start working in isolation.

Note: Remember to initialize your development environment in each new worktree according to your project's setup. Depending on your stack, this might include running dependency installation (npm install, yarn), setting up virtual environments, or following your project's standard build process.

How to exit a worktree session

When you exit a worktree session (using /quit or Ctrl+C), Gemini automatically determines whether to clean up or preserve the worktree based on the presence of changes.

• Automatic removal: If the worktree is completely clean—meaning it has no uncommitted changes and no new commits have been made—Gemini automatically removes the worktree directory and deletes the temporary branch.
• Safe preservation: If Gemini detects any changes, it leaves the worktree intact so your work is not lost. Preservation occurs if:
  • You have uncommitted changes (modified files, staged changes, or new untracked files).
  • You have made new commits on the worktree branch since the session started.

Gemini prioritizes a fast and safe exit: it does not display an interactive prompt to ask whether to keep the worktree. Instead, it ensures your work is safely preserved by default if any modifications are detected.

Resuming work in a worktree

If a worktree was preserved because it contained changes, Gemini displays instructions on how to resume your work when you exit.

To resume a session in a preserved worktree, navigate to the worktree directory and start Gemini CLI with the --resume flag:

cd .gemini/worktrees/feature-auth
gemini --resume latest

Managing worktrees manually

For more control over worktree location and branch configuration, or to clean up a preserved worktree, you can use Git directly:

• Clean up a preserved worktree:

  git worktree remove .gemini/worktrees/feature-auth --force
  git branch -D worktree-feature-auth
  

• Create a worktree manually:

  git worktree add ../project-feature-a -b feature-a
  cd ../project-feature-a && gemini