mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-03-26 05:50:56 -07:00
e5f4093058
Implements the /worktree slash command, allowing users to switch the active session to a new isolated Git worktree without restarting the CLI. Key changes: - Added '/worktree' slash command with streamlined messaging. - Updated 'Config' class to support runtime updates to the target directory. - Introduced 'WorkingDirectoryChanged' event to notify UI and hooks of path changes. - Added comprehensive tests and updated documentation.
144 lines
4.6 KiB
Markdown
144 lines
4.6 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
|
|
|
|
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.
|
|
|
|
```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
|
|
```
|
|
|
|
### 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:**
|
|
|
|
```text
|
|
/worktree feature-auth
|
|
```
|
|
|
|
- **Switch with a random name:**
|
|
```text
|
|
/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:
|
|
|
|
```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
|