Git WorkGrove

A code-workspace friendly worktree explorer for VS Code

Git WorkGrove provides first-class .code-workspace support for git worktrees. It appears in the Source Control view, letting you browse worktrees and directly open their workspace files.

Why This Extension Exists

Git worktrees are powerful for parallel development — but VS Code and its extensions don't handle .code-workspace files well in worktree workflows.

The problem: When you switch to a worktree, tools open the folder — not the .code-workspace file. This means:

• Dev server output shows relative paths that can't be clicked to open files
• Multi-root workspace configurations are silently lost
• Workspace-scoped settings and tasks don't apply

This has been a long-standing pain point across both VS Code and GitLens:

• [Open workspace file instead of root folder when opening a worktree (GitLens #4016)](https://github.com/gitkraken/vscode-gitlens/issues/4016) — the core issue
• [Workspace settings are lost when switching between worktrees (GitLens #1956)](https://github.com/gitkraken/vscode-gitlens/issues/1956)
• [Improve workspace + worktree experience (GitLens #4453)](https://github.com/gitkraken/vscode-gitlens/issues/4453) — umbrella tracking issue
• [Git - Support git worktrees in workspace (VS Code #68038)](https://github.com/microsoft/vscode/issues/68038) — original feature request

What Git WorkGrove does — and doesn't do:

Git WorkGrove focuses on one thing: making .code-workspace files a first-class citizen in the worktree workflow. It does not manage worktrees — creating, deleting, and switching worktrees is best handled by VS Code's built-in git support or extensions like GitLens.

If VS Code or GitLens ever ships proper .code-workspace support for worktrees, this extension will have served its purpose.

Features

• Source Control tree view — Browse all worktrees with their .code-workspace files
• Worktree names — Labels match git worktree names instead of raw paths
• Favorites — Pin any item (repository, worktree, workspace file) to the top with drag-and-drop reordering
• Current indicator — Green icon and badge highlight the currently open item
• Customizable templates — Full control over labels and descriptions for all 8 item types
• Custom Commands — Define your own context menu commands with template variable support
• Open in Terminal — Right-click to open a terminal at any worktree or workspace file location
• Prune — Clean up stale worktree records
• Live updates — FileSystemWatcher detects worktree changes automatically

Usage

Tree View

Git WorkGrove adds a WORKGROVE panel in the Source Control sidebar. It shows:

1. Favorites — Pinned items at the top (if any exist)
2. Repository — The main worktree (collapsible, with workspace files as children)
3. Linked worktrees — All other worktrees (alphabetically sorted, each with workspace files)

Click a workspace file to open it. Click a worktree to expand/collapse its children.

Context Menu (Right-Click)

Right-click any item in the tree to access:

Favorite-specific actions appear as inline buttons:

You can also drag and drop favorites to reorder them.

View Title Actions

The WORKGROVE panel header provides:

Open Behavior

When you click a workspace file, the behavior depends on the openBehavior setting:

• ask (default) — Shows a picker with options: Open in New Window, Open in Current Window, Open in Terminal, plus "Always" variants that persist your choice
• newWindow — Always opens in a new window
• currentWindow — Always opens in the current window
• terminal — Always opens a terminal at the item's location

Current Indicator

The currently open workspace or worktree is highlighted with:

• A green-tinted icon
• A green dot badge (●)

Clicking the current item does nothing (it's already open).

Settings

Open VS Code Settings (Cmd+, / Ctrl+,) and search for git-work-grove:

Custom Commands

Define custom commands that appear in the tree view context menu. Two settings are available:

• git-work-grove.customCommands.directory — for repository/worktree items
• git-work-grove.customCommands.workspace — for workspace file items

Entry Schema

Execution modes:

• "spawn" (default) — Runs the command as a detached background process (fire-and-forget). The process outlives the extension and runs silently.
• "terminal" — Runs the command in a VS Code integrated terminal. The terminal stays open so you can see output and interact with the process. Ideal for dev servers, REPLs, and interactive CLI tools.

Template Variables

Directory items (customCommands.directory): {name}, {branch}, {ref}, {head}, {path}

Workspace items (customCommands.workspace): all of the above, plus {dir} (parent directory) and {worktree} (parent worktree folder name)

Both command and env values support template variables with fallback syntax ({branch|detached}) and conditional sections ({?branch}...{/branch}). See Template Customization for syntax reference.

Examples

Run a dev server in terminal:

{
  "git-work-grove.customCommands.directory": [
    {
      "command": ["npm", "run", "dev"],
      "env": { "NODE_ENV": "development" },
      "label": "Run Dev Server",
      "mode": "terminal"
    }
  ]
}

Open in an external terminal emulator (macOS):

{
  "git-work-grove.customCommands.directory": [
    {
      "command": ["open", "-a", "Terminal", "{path}"],
      "label": "Open in Terminal.app"
    }
  ]
}

Other terminal emulators:

Open in an external editor:

{
  "git-work-grove.customCommands.directory": [
    {
      "command": ["zed", "{path}"],
      "label": "Open in Zed"
    }
  ]
}

Environment variables with template variables:

{
  "git-work-grove.customCommands.directory": [
    {
      "command": ["open", "-a", "Ghostty", "--args", "--working-directory={path}"],
      "env": { "GHOSTTY_TITLE": "{ref}" },
      "label": "Open in Ghostty"
    }
  ]
}

Multiple commands (shown as QuickPick):

{
  "git-work-grove.customCommands.directory": [
    {
      "command": ["npm", "run", "dev"],
      "label": "Run Dev Server",
      "mode": "terminal"
    },
    {
      "command": ["zed", "{path}"],
      "label": "Open in Zed"
    }
  ]
}

Start Claude Code in a worktree:

{
  "git-work-grove.customCommands.directory": [
    {
      "command": ["claude"],
      "label": "Claude Code",
      "mode": "terminal"
    }
  ]
}

Workspace file commands — use {dir} for the parent directory or {path} for the file itself:

{
  "git-work-grove.customCommands.workspace": [
    {
      "command": ["open", "-a", "Terminal", "{dir}"],
      "label": "Open dir in Terminal.app"
    }
  ]
}

Known Limitation

Terminal mode ("mode": "terminal") uses the shell-quote library for POSIX-style shell quoting. This may not work correctly in PowerShell terminals (Windows, macOS, or Linux) for commands with arguments containing spaces or special characters. If your VS Code terminal profile uses PowerShell, prefer "mode": "spawn" for such commands.

Template Customization

All tree item labels and descriptions are customizable. Templates support variables like {name}, {branch}, {ref}, fallback syntax ({branch|detached}), and conditional sections ({?branch}({branch}){/branch}).

See Template Customization for all 8 item types, available variables, and examples.

Commands

All commands use the Git WorkGrove: prefix. Some are available via the Command Palette (Cmd+Shift+P / Ctrl+Shift+P), while others appear only in the tree view context menu or inline buttons.

Command Palette

Context Menu Only

These commands appear when right-clicking items in the tree view:

Documentation

• Template Customization — Customize labels and descriptions for all item types with template variables

Specifications

Design documents for contributors and AI-assisted development:

• Tree Structure — 4 fundamental types, node hierarchy, icons, collapsible states
• Current Indicator — Single-current-item rule, detection logic
• Favorites — Data model, resolution, ordering, stale cleanup
• Templates — 8 template types, variables, defaults, selection logic
• Commands — All commands, menu placement, behaviors
• Workspace Scanning — File discovery, include/exclude patterns
• Open Behavior — Open modes, URI resolution, click handling
• Open in Terminal — CWD resolution, terminal naming, prunable guard
• Empty States — Git unavailable, no repository, no worktrees messages
• Custom Commands — Custom commands: settings, execution, context menu

Installation

VS Code Marketplace

Install from the Visual Studio Marketplace:

1. Open VS Code
2. Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
3. Search for Git WorkGrove
4. Click Install

Open VSX Registry

Install from Open VSX for VS Code alternatives (VSCodium, code-server, Gitpod, etc.):

1. Open your editor's extension panel
2. Search for Git WorkGrove
3. Click Install

Requirements

• VS Code 1.95.0+
• Git installed and available in PATH

License

MIT