Workspace Model

Grove is a workspace-aware toolkit. The Workspace Model is a hierarchical representation of all your local projects that lets you specify which repositories Grove should operate on.

Workspace Discovery

Grove discovers projects by scanning search_paths defined in your global configuration (~/.config/grove/grove.yml). This builds an in-memory graph of all known projects that Grove tools use for context-aware functionality.

A typical global configuration might look like this:

yaml
# Defines root directories to search for projects and ecosystems
search_paths:
  work:
    path: ~/Work
    enabled: true
  personal:
    path: ~/Projects
    enabled: true

Workspace Configuration

Workspaces are configured via grove.yml files in the repository root. For integrating Grove with non-Grove repositories, you can use .grove.yml or .cx.work as alternative configuration filenames. When added to your global .gitignore, these files let you configure Grove-specific settings without committing them to source control.

The Workspace Hierarchy

Grove classifies repositories into different kinds, creating a hierarchy that mirrors common development patterns for both standalone projects and multi-repository ecosystems.

Key WorkspaceKind classifications:

Standalone Projects

  • StandaloneProject: A single Git repository with a grove.yml file.
  • StandaloneProjectWorktree: A Git worktree of a StandaloneProject, located in a .grove-worktrees directory.

Ecosystems

An Ecosystem is a meta-repository that contains multiple Grove projects, each with their own .git repository. Ecosystems coordinate multiple independent repositories and are identified by a grove.yml file with a workspaces key. Projects within an ecosystem can be Git submodules or standalone directories.

  • EcosystemRoot: The main repository of an ecosystem.
  • EcosystemSubProject: A project (e.g., submodule) inside an EcosystemRoot.
  • EcosystemWorktree: A Git worktree of the entire ecosystem, creating an isolated environment for work on cross-cutting features without disrupting the main branch.
  • EcosystemSubProjectWorktree: A Git worktree of an EcosystemSubProject.
  • EcosystemWorktreeSubProject: A project inside an EcosystemWorktree, created when a submodule is initialized with git submodule update rather than as a linked worktree.
  • EcosystemWorktreeSubProjectWorktree: The “linked development” state—a Git worktree of a sub-project located inside an EcosystemWorktree. This setup enables working on a feature branch of a sub-project within the context of an ecosystem-wide feature.

This diagram illustrates the relationship between these kinds and their on-disk structure:

mermaid
graph TD
    subgraph Standalone Project
        SP["my-project<br><small>/path/to/my-project</small><br><b>StandaloneProject</b>"]
        SP_WT["feature<br><small>in .grove-worktrees/</small><br><b>StandaloneProjectWorktree</b>"]
        SP -. "git worktree" .-> SP_WT
    end

    subgraph Ecosystem
        ER["my-ecosystem<br><small>/path/to/my-ecosystem</small><br><b>EcosystemRoot</b>"]

        SUB_P["sub-project<br><small>in my-ecosystem/</small><br><b>EcosystemSubProject</b>"]
        ER -- "contains" --> SUB_P

        SUB_P_WT["sub-feature<br><small>in sub-project/.grove-worktrees/</small><br><b>EcosystemSubProjectWorktree</b>"]
        SUB_P -. "git worktree" .-> SUB_P_WT

        EW["eco-feature<br><small>in my-ecosystem/.grove-worktrees/</small><br><b>EcosystemWorktree</b>"]
        ER -. "git worktree" .-> EW

        EW_SUB_P["sub-project<br><small>in eco-feature/</small><br><b>EcosystemWorktreeSubProject</b><br><small>(full checkout)</small>"]
        EW -- "contains" --> EW_SUB_P

        EW_SUB_PW["sub-project<br><small>in eco-feature/</small><br><b>EcosystemWorktreeSubProjectWorktree</b><br><small>(linked worktree)</small>"]
        EW -- "contains" --> EW_SUB_PW
    end

What the Workspace Model Enables

Context-Aware Operations

Tools query the workspace model to determine their operational context. This allows behavior to adapt based on location—grove run scopes to sub-projects within an ecosystem worktree, while nb stores notes in the parent project directory rather than temporary worktree locations.

Cross-Project References

Portable aliases reference projects without hardcoded paths. cx uses this in .grove/rules files:

groverules
# Reference files from any discovered project
@a:core/pkg/workspace/types.go

# Exclude test files from a project in an ecosystem worktree
!@a:my-ecosystem:feature-branch:core/**/*_test.go

Alias resolution prioritizes sibling projects within the same ecosystem.

Multi-Repository Orchestration

Commands can operate across all discovered projects: grove deps bump updates dependencies, grove run <command> executes commands in each project, and docgen aggregate collects documentation from all projects.

Isolated Development

The workspace system manages Git worktrees with standardized functions. For ecosystem projects with submodules, this sets up linked local worktrees rather than new clones, enabling simultaneous development across multiple repositories. flow creates dedicated worktrees for development plans.

Tools like grove ws and nb tui render interactive trees of all workspaces. Each workspace generates a unique identifier (e.g., my-ecosystem_my-project_feature-branch) used by nav for session names and grove-proxy for local domains (e.g., api.feature-branch.my-project.localhost).