grove

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

(★ 51)

A fast, intuitive CLI that makes Git worktrees as simple as switching branches.

grove Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🌳 Grove

[![GitHub release](https://img.shields.io/github/v/release/sQVe/grove?style=flat-square)](https://github.com/sQVe/grove/releases/latest)
[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://raw.githubusercontent.com/sQVe/grove/main/LICENSE)

_A fast, intuitive CLI that makes Git worktrees as simple as switching branches._

**Without Grove:**

```bash
git clone --bare git@github.com:org/repo.git .bare
echo "gitdir: ./.bare" > .git
git worktree add main
cd main
cp ../other-worktree/.env . # Don't forget this
npm install                 # Or this
# Later: cd ../feat-auth to switch
```

**With Grove:**

```bash
grove clone git@github.com:org/repo
grove add feat/auth --switch # .env copied, hooks run automatically
grove switch main            # Just like git checkout, but each branch keeps its own directory
```

https://github.com/user-attachments/assets/27f3c1f4-ff58-471e-87a3-8fd0c32ad474

> [!NOTE]
> Grove is under active development. Core functionality is stable, but APIs may change between major versions.

---

<details>
<summary>New to worktrees?</summary>

Git worktrees let you work on multiple branches simultaneously in separate directories. No stashing. No "wrong branch" mistakes. Your work stays exactly where you left it.

The catch: `git worktree` is clunky. Grove makes it feel like `git checkout` — but each branch gets its own persistent directory.

</details>

## 📋 Requirements

- **Git 2.48+** — Grove uses `--relative-paths` for portable worktrees

## 📦 Installation

### Quick install (Linux/macOS)

```bash
curl -fsSL https://raw.githubusercontent.com/sQVe/grove/main/install.sh | sh
```

### Go install

```bash
go install github.com/sqve/grove/cmd/grove@latest
```

### From source

```bash
git clone https://github.com/sQVe/grove && cd grove
go build -o grove ./cmd/grove
sudo mv grove /usr/local/bin/
```

### Package managers

Download `.deb` or `.rpm` packages from [GitHub Releases](https://github.com/sQVe/grove/releases/latest).

### Optional: GitHub CLI

Grove works without additional dependencies, but installing the [GitHub CLI](https://cli.github.com/) (`gh`) enables enhanced features:

- **PR worktrees**: Create worktrees from pull requests with `grove add --pr 123` or `grove clone https://github.com/owner/repo/pull/123`
- **Squash-merge detection**: `grove prune` accurately detects branches merged via GitHub's squash-and-merge, even with multiple commits. Without `gh`, only single-commit squash merges are detected via git.

See [GitHub CLI installation](https://github.com/cli/cli#installation) for setup instructions.

## 🔧 Setup

### Shell Integration (Required)

Without this, `grove switch` only prints a path — you'd have to `cd` manually. Add to your shell config:

```bash
# bash (~/.bashrc) or zsh (~/.zshrc)
eval "$(grove switch shell-init)"

# fish (~/.config/fish/config.fish)
grove switch shell-init | source

# powershell ($PROFILE)
grove switch shell-init | Invoke-Expression
```

### Shell Completion

Tab completion for commands, flags, and worktree names.

```bash
# bash
eval "$(grove completion bash)"

# zsh
eval "$(grove completion zsh)"

# fish
grove completion fish | source

# powershell
grove completion powershell | Invoke-Expression
```

## 🚀 Quick Start

```bash
# Clone a repository
grove clone https://github.com/owner/repo
cd repo

# Start a feature
grove add feat/auth --switch

# Check your worktrees
grove list

# Switch back to main
grove switch main

# Clean up when done
grove remove feat/auth --branch
```

## 📗 Commands

<details>
<summary><code>grove clone &lt;url&gt; [directory]</code></summary>

Clone a repository into a Grove workspace.

**Flags:**

- `--branches <list>` — Comma-separated branches to create worktrees for
- `--shallow` — Shallow clone (depth=1)
- `-v, --verbose` — Show git output

**Examples:**

```bash
grove clone https://github.com/owner/repo
grove clone https://github.com/owner/repo my-project
grove clone https://github.com/owner/repo --branches main,develop
grove clone https://github.com/owner/repo/pull/123 # Clone and checkout PR
```

</details>

<details>
<summary><code>grove init new [directory]</code> / <code>grove init convert</code></summary>

Initialize a Grove workspace.

**Subcommands:**

- `new [directory]` — Create new workspace
- `convert` — Convert existing repository

**Flags (convert):**

- `--branches <list>` — Additional branches to create worktrees for
- `-v, --verbose` — Show git output

**Examples:**

```bash
grove init new my-project
grove init convert
grove init convert --branches develop,staging
```

</details>

<details>
<summary><code>grove add [branch|PR-URL|ref]</code></summary>

Add a worktree for a branch, pull request, or ref.

**Flags:**

- `-s, --switch` — Switch to worktree after creating
- `--base <branch>` — Create new branch from base instead of HEAD
- `--name <name>` — Custom directory name
- `-d, --detach` — Detached HEAD state
- `--pr <number>` — Create worktree for a pull request
- `--from <worktree>` — Source worktree for file preservation (name or branch)
- `--reset` — Reset diverged PR branch to match remote (use with `--pr`)

**Examples:**

```bash
grove add feat/auth
grove add feat/auth --switch
grove add --base main feat/auth
grove add --pr 123             # PR by number
grove add --pr 123 --reset     # PR, discarding local commits
grove add --detach v1.0.0      # Tag in detached HEAD
grove add --from dev feat/auth # Copy .env from dev worktree
```

</details>

<details>
<summary><code>grove switch &lt;worktree&gt;</code></summary>

Switch to a worktree by directory or branch name.

Requires shell integration (see Setup section).

**Examples:**

```bash
grove switch main
grove switch feat-auth
grove switch feat/auth
```

</details>

<details>
<summary><code>grove list</code></summary>

List all worktrees with status.

**Flags:**

- `--fast` — Skip remote sync checks
- `--filter <status>` — Filter by: `dirty`, `ahead`, `behind`, `gone`, `locked`
- `--json` — JSON output
- `-v, --verbose` — Show paths and upstreams

**Examples:**

```bash
grove list
grove list --fast
grove list --filter dirty
grove list --filter ahead,behind
grove list --json
```

</details>

<details>
<summary><code>grove status</code></summary>

Show current worktree status.

**Flags:**

- `-v, --verbose` — Show all diagnostic sections
- `--json` — JSON output

**Examples:**

```bash
grove status
grove status --verbose
```

</details>

<details>
<summary><code>grove remove &lt;worktree&gt;...</code></summary>

Remove one or more worktrees.

**Flags:**

- `-f, --force` — Remove even if dirty or locked
- `--branch` — Also delete the branch

**Examples:**

```bash
grove remove feat-auth
grove remove feat-auth --branch
grove remove --force wip
grove remove feat-auth bugfix-123 # Remove multiple
```

</details>

<details>
<summary><code>grove move &lt;worktree&gt; &lt;new-branch&gt;</code></summary>

Rename a branch and its worktree.

**Examples:**

```bash
grove move feat/old feat/new
```

</details>

<details>
<summary><code>grove lock &lt;worktree&gt;...</code></summary>

Lock one or more worktrees to prevent removal.

**Flags:**

- `--reason <text>` — Reason for locking

**Examples:**

```bash
grove lock main
grove lock release --reason "Production release"
grove lock feat-auth bugfix-123 # Lock multiple
```

</details>

<details>
<summary><code>grove unlock &lt;worktree&gt;...</code></summary>

Unlock one or more worktrees.

**Examples:**

```bash
grove unlock feat-auth
grove unlock feat-auth bugfix-123 # Unlock multiple
```

</details>

<details>
<summary><code>grove prune</code></summary>

Remove worktrees with deleted upstream branches. Dry-run by default.

When removing worktrees whose upstream was deleted on remote, local branches are also deleted.

**Flags:**

- `--commit` — Actually remove (default is dry-run)
- `-f, --force` — Remove even if dirty, locked, or unpushed
- `--stale <duration>` — Include inactive worktrees (e.g., `30d`, `2w`)
- `--merged` — Include branches merged into default branch
- `--detached` — Include detached worktrees

**Examples:**

```bash
grove prune          # Dry-run
grove prune --commit # Actually remove
grove prune --stale 30d --commit
grove prune --merged --commit
grove prune --detached --commit
```

</details>

<details>
<summary><code>grove exec [worktrees...] -- &lt;command&gt;</code></summary>

Execute a command in worktrees.

**Flags:**

- `-a, --all` — Execute in all worktrees
- `--fail-fast` — Stop on first failure

**Examples:**

```bash
grove exec --all -- npm install
grove exec main feat-auth -- git pull
grove exec --all --fail-fast -- go build
grove exec --all -- bash -c "npm install && npm test"
```

</details>

<details>
<summary><code>grove config &lt;subcommand&gt;</code></summary>

Manage configuration.

**Subcommands:**

- `list` — Show all settings
- `get <key>` — Get value
- `set <key> <value>` — Set value (requires `--shared` or `--global`)
- `unset <key>` — Remove setting (requires `--shared` or `--global`)
- `init` — Create `.grove.toml` template

**Flags:**

- `--shared` — Target `.grove.toml`
- `--global` — Target git config

**Examples:**

```bash
grove config list
grove config get preserve.patterns
grove config set --global plain true
grove config set --shared autolock.patterns "main,release/*"
grove config init
```

</details>

<details>
<summary><code>grove doctor</code></summary>

Diagnose workspace issues.

**Flags:**

- `--fix` — Auto-fix safe issues
- `--json` — JSON output
- `--perf` — Disk space analysis

**Detects:**

- Dependency versions (Git 2.48+, optional gh CLI)
- Broken `.git` pointers
- Stale worktree entries
- Unreachable remotes
- Invalid `.grove.toml` syntax
- Hook commands not found in PATH
- Stale lock files

**Examples:**

```bash
grove doctor
grove doctor --fix
grove doctor --perf
```

</details>

## ⚙ Configuration

Grove uses a two-layer configuration system:

- **`.grove.toml`** — Team settings (checked into repository)
- **Git config** (`~/.gitconfig`) — Personal settings

Run `grove config init` to create a `.grove.toml` template.

<details>
<summary>Default configuration</summary>

```toml
# Grove - Git worktree management
# https://github.com/sqve/grove

[preserve]
# Files to copy from the current worktree when creating a new one.
# Useful for environment files and local configuration that shouldn't be in git.
# Supports glob patterns. These patterns override git config grove.preserve.
patterns = [
  ".env",
  ".env.keys",
  ".env.local",
  ".env.*.local",
  ".envrc",
  ".grove.toml",
  "docker-compose.override.yml",
]

# Path segments to exclude from preservation.
# Files containing any of these path segments will be skipped.
exclude = [
  # Caches
  ".cache",
  "__pycache__",

# Build output
  "build",
  "coverage",
  "dist",
  "out",
  "target",

# Dependencies
  ".venv",
  "node_modules",
  "vendor",
  "venv",
]

[link]
# Directories to symlink from the source worktree when creating a new one.
# Useful for sharing tool state (e.g., .claude) across worktrees.
# Matched against directory names in the worktree root.
# Creates relative symlinks so the workspace remains portable.
patterns = []

[hooks]
# Shell commands to run after creating a worktree.
# Runs sequentially, stops on first failure.
# Examples: ["npm install"], ["go mod download", "make setup"]
add = []

[autolock]
# Branch patterns to automatically lock when creating worktrees.
# Locked worktrees are protected from accidental deletion.
# Supports exact matches and trailing /* wildcards (e.g., "release/*").
patterns = ["develop", "main", "master"]

# Use Nerd Font icons in output (when not in plain mode).
nerd_fonts = true

# Threshold for marking worktrees as stale (no commits within this period).
# Format: number followed by d (days), w (weeks), or m (months).
stale_threshold = "30d"

# Disable colors and symbols in output.
plain = false

# Enable debug logging.
debug = false
```

</details>

## Recipes

### Git hooks managers

[Husky](https://typicode.github.io/husky/) and [lefthook](https://github.com/evilmartians/lefthook) set `core.hooksPath` to a relative path (`.husky` or `.lefthook`). In a bare worktree setup, this config is shared across all worktrees via `.bare/config`. The relative path resolves correctly from any worktree because the directory exists in every checkout. Re-run the installer after worktree creation to ensure the path is set:

<details>
<summary>Husky</summary>

```toml
[hooks]
add = ["npm install", "npx husky"]
```

</details>

<details>
<summary>lefthook</summary>

```toml
[hooks]
add = ["lefthook install"]
```

</details>

[pre-commit](https://pre-commit.com/) writes hook scripts directly into the git hooks directory (`.bare/hooks/`), which is shared by all worktrees. Run `pre-commit install` once from any worktree — no Grove hook needed.

### Next.js shared build caches

Next.js build output (`.next`) and Turborepo cache (`.turbo`) can be shared across worktrees to avoid redundant rebuilds. Never symlink `node_modules/` — it contains absolute paths and branch-specific dependency versions.

```toml
[link]
patterns = [".next", ".turbo"]
```

### Rust shared target directory

Rust `target/` directories consume significant disk space. Sharing via symlink avoids duplicate compilation across worktrees.

```toml
[link]
patterns = ["target"]
```

Parallel `cargo build` across worktrees sharing the same target directory will serialize on file locks.

### AI coding tools

AI coding tools store local configuration in git-ignored files that are lost in new worktrees. Preserve them to carry project context and settings across worktrees.

```toml
[preserve]
patterns = [
  "CLAUDE.local.md",
  ".claude/settings.local.json",
  ".aider.conf.yml",
  ".copilot/config.json",
]
```

These patterns are additive — they extend the default preserve patterns, not replace them.

## 🤝 Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

grove

grove Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

grove

grove Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README