Installation

Grove is a global Node.js CLI. It requires Node 18+ and is available on npm.

Prerequisites

Tool	Required for
git	All worktree operations
gh	PR checkout (grove start <PR#>), GitHub sync
docker	Docker Compose environment management

gh and docker are optional — Grove degrades gracefully if they're missing. Only the features that depend on them won't activate.

Check your Node version:

node --version   # must be 18+

Install

npm install -g @gitgrove/cli@alpha

Verify it worked:

grove --version

Contributing / building from source

If you want to contribute or run from source:

git clone https://github.com/christinabranson/git-grove.git
cd git-grove
npm install
npm run build
npm link

npm link makes the grove binary available globally, pointing at your local build.

Global gitignore

Grove creates per-worktree files that should never be committed. Add them to your global gitignore so you don't have to touch each repo's .gitignore:

# See where your global gitignore lives
git config --global core.excludesfile

# Add the grove entries
echo '.env.worktree' >> ~/.gitignore_global
echo '.worktree-manifest.json' >> ~/.gitignore_global
echo '.grove/meta.json' >> ~/.gitignore_global

If you haven't set one up yet:

echo '.env.worktree' >> ~/.gitignore_global
echo '.worktree-manifest.json' >> ~/.gitignore_global
echo '.grove/meta.json' >> ~/.gitignore_global
git config --global core.excludesfile ~/.gitignore_global

File	What it is
.env.worktree	Port assignments and Compose project name (per branch)
.worktree-manifest.json	Agent status file written at runtime
.grove/meta.json	Base branch recorded when creating a worktree with --new

These are machine-local and per-session — committing them would break other developers' environments.

Note: .grove/config.json is different — it describes how the project works and should be committed. Only the runtime state files above need to stay out of git.

Editor detection

Grove auto-detects your editor for grove open — no config required. It checks in order:

1. editor field in .grove/config.json
2. $VISUAL environment variable
3. $EDITOR environment variable
4. Scans PATH for code, cursor, windsurf, vim, nano
5. On macOS: checks standard app bundle locations (so VS Code works even if code isn't in PATH)

Next steps

• Quick Start — get to a working setup in 5 minutes
• Core Concepts — understand worktrees, providers, and manifests

Troubleshooting

grove: command not found

npm install -g puts the binary in npm's global bin directory. If that directory isn't in your PATH:

# Find where npm puts global binaries
npm bin -g

# Add it to your PATH (add this to ~/.zshrc or ~/.bashrc)
export PATH="$(npm bin -g):$PATH"

# Then reload your shell
source ~/.zshrc   # or ~/.bashrc

git worktree: unknown command

Your Git version is too old. Grove requires Git 2.5+, which introduced worktree support.

git --version   # check your version

# macOS: update via Homebrew
brew install git

# Ubuntu/Debian
sudo apt-get install git

After updating, open a new terminal and verify:

git --version        # should be 2.5 or higher
git worktree list    # should work without error

grove open opens the wrong editor (or nothing)

Grove auto-detects your editor in priority order: .grove/config.json → $VISUAL → $EDITOR → PATH scan → macOS app bundles.

To force a specific editor, set $VISUAL in your shell profile:

# ~/.zshrc or ~/.bashrc
export VISUAL="code"   # VS Code
export VISUAL="cursor" # Cursor
export VISUAL="vim"    # Vim

Or configure it explicitly in .grove/config.json:

{ "editor": "code" }

Permission errors during npm install -g

If you see EACCES: permission denied:

# Option 1: fix npm's global directory permissions (recommended)
# See: https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally

# Option 2: use a Node version manager (nvm/fnm) — avoids permission issues entirely
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

VS Code opens a file instead of a folder

grove open passes the worktree path to your editor. If VS Code opens a file picker instead of the folder, ensure the code CLI is installed:

1. Open VS Code
2. Open the Command Palette (⌘⇧P on macOS, Ctrl⇧P on Linux/Windows)
3. Run: Shell Command: Install 'code' command in PATH

Then grove open will open the worktree as a VS Code workspace.