A bird's-eye view of your git workspaces

Canopy is a CLI/TUI tool that manages isolated workspaces for your development work. It creates dedicated directories for each workspace, containing git worktrees for all relevant repositories, while keeping canonical clones centralized.

• The Metaphor
• Features
• Installation
• Quick Start
• Documentation
• Command Reference
• Configuration
• License

Think of Canopy as your vantage point above the forest. Just as a canopy provides a bird's-eye view of the trees and branches below, this tool gives you an elevated perspective to see and organize all your git workspaces and branches. The TUI provides a literal canopy-level dashboard where you can survey your entire development landscape—multiple repositories (trees), their branches, and the workspaces where you tend them.

• Isolated Workspaces — Dedicated directories for each task (e.g., ~/workspaces/PROJ-123)
• Git Worktrees — Automatic worktree creation for multiple repos on the same branch
• Centralized Storage — Canonical repos cloned once and reused across all workspaces
• Interactive TUI — Terminal UI for managing workspaces at a glance
• Lifecycle Hooks — Run custom commands on workspace creation and closure
• Pattern Matching — Auto-assign repos to workspaces based on ID patterns

go install github.com/alexisbeaulieu97/canopy/cmd/canopy@latest

git clone https://github.com/alexisbeaulieu97/canopy.git
cd canopy
make install

This embeds version, commit hash, and build date into the binary.

# Initialize configuration
canopy init

# Add repositories you work with
canopy repo add https://github.com/myorg/backend.git
canopy repo add https://github.com/myorg/frontend.git

# Create a workspace
canopy workspace new PROJ-123 --repos backend,frontend

# Start working
cd ~/workspaces/PROJ-123

See the Quick Start Guide for a complete walkthrough.

Flags for workspace new:

• --repos — Comma-separated list of repositories
• --branch — Custom branch name (defaults to ID)
• --print-path — Print the created workspace path
• --no-hooks — Skip post_create hooks
• --hooks-only — Run post_create hooks without creating workspace

Flags for workspace list:

• --status — Show git status for each repository
• --timeout — Timeout for status check per workspace (default: 5s)
• --closed — List closed workspaces
• --json — Output in JSON format

Flags for workspace close:

• --keep — Keep metadata for later restoration
• --delete — Delete without keeping metadata
• --force — Force close even with uncommitted changes
• --dry-run — Preview what would be deleted
• --no-hooks — Skip pre_close hooks
• --hooks-only — Run pre_close hooks without closing workspace
• --pattern — Close workspaces matching a regex pattern
• --all — Close all workspaces (equivalent to --pattern ".*")

Flags for workspace sync:

• --timeout — Timeout for each repository sync (default: 60s)
• --json — Output in JSON format
• --pattern — Sync workspaces matching a regex pattern
• --all — Sync all workspaces (equivalent to --pattern ".*")

Flags for workspace branch:

• --create — Create branch if it doesn't exist
• --pattern — Switch branches for workspaces matching a regex pattern
• --all — Switch branches for all workspaces (equivalent to --pattern ".*")

Use short aliases for repositories:

canopy tui

See Configuration to customize keybindings.

Version output example:

canopy version v1.0.0
commit: abc1234
built: 2025-01-15T10:30:00Z
go: go1.21.0

Use canopy version --json for machine-readable output or canopy --version for a short version string.

Configuration is stored in ~/.canopy/config.yaml:

projects_root: ~/projects
workspaces_root: ~/workspaces
closed_root: ~/.canopy/closed
workspace_close_default: delete  # default; set to "archive" to keep metadata

defaults:
  workspace_patterns:
    - pattern: "^PROJ-"
      repos: ["backend", "frontend"]

templates:
  backend:
    description: "Backend workspace defaults"
    repos: ["backend", "common"]
    default_branch: "main"
  frontend:
    description: "Frontend workspace defaults"
    repos: ["frontend", "ui-kit", "design-system"]
    setup_commands:
      - "npm install"

See Configuration Reference for all options.

Use templates to create common workspace layouts quickly:

canopy workspace new PROJ-123 --template backend
canopy workspace new PROJ-456 --template frontend --repos extra-lib

Workspace creation fails with "unknown repository"

The repository must be cloned or registered first:

# Clone the repository
canopy repo add https://github.com/myorg/repo.git

# Or register an alias
canopy repo register repo https://github.com/myorg/repo.git

Git operations timeout

Configure retry settings in ~/.canopy/config.yaml:

git:
  retry:
    max_attempts: 5
    initial_delay: "2s"
    max_delay: "60s"

"Repository has uncommitted changes" error

Either commit/stash changes or use --force:

canopy workspace close PROJ-123 --force

Configuration validation errors

Run canopy check to validate your configuration:

canopy check

For machine-readable error handling, see the Error Codes Reference.

MIT