mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-03-26 14:01:14 -07:00
94ce4aba8b
Introduces a central Git worktree management system to enable isolated, parallel agent orchestration. This allows running multiple Gemini sessions on different branches within the same repository without file contention. Key Features: - Added 'WorktreeService' in @google/gemini-cli-core to manage creation, lifecycle, and cleanup of Git worktrees. - Implemented smart cleanup logic that detects untracked files and new commits, automatically preserving worktrees with uncommitted work. - Added '--worktree' (-w) flag to the CLI to launch sessions in fresh, isolated environments. - Enhanced the session exit experience with detailed status messages and instructions for resuming work in preserved worktrees.
113 lines
3.8 KiB
Markdown
113 lines
3.8 KiB
Markdown
# 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](./session-management.md).
|
|
|
|
> **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](https://git-scm.com/docs/git-worktree).
|
|
|
|
## 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`:
|
|
|
|
```json
|
|
{
|
|
"experimental": {
|
|
"worktrees": true
|
|
}
|
|
}
|
|
```
|
|
|
|
## How to use Git worktrees
|
|
|
|
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.
|
|
|
|
```bash
|
|
gemini --worktree feature-auth
|
|
```
|
|
|
|
- **Start with a random name:** If you omit the name, Gemini generates a random
|
|
one automatically (for example, `worktree-a1b2c3d4`).
|
|
|
|
```bash
|
|
gemini --worktree
|
|
```
|
|
|
|
> **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:
|
|
|
|
```bash
|
|
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:**
|
|
```bash
|
|
git worktree remove .gemini/worktrees/feature-auth --force
|
|
git branch -D worktree-feature-auth
|
|
```
|
|
- **Create a worktree manually:**
|
|
```bash
|
|
git worktree add ../project-feature-a -b feature-a
|
|
cd ../project-feature-a && gemini
|
|
```
|
|
|
|
[Open an issue]: https://github.com/google-gemini/gemini-cli/issues
|