> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wazoo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace

> wspace is a Git-native CLI that manages multi-repository workspaces without Git submodules.

`wspace` (published as [`@wazoo/workspace`](https://jsr.io/@wazoo/workspace)) is
a Git-native CLI that manages multi-repository Wazoo workspaces without Git
submodules. It consolidates workspace conventions into a manifest (`repos.json`)
and standardizes feature development with Git worktrees.

## Overview

Complex applications and agent infrastructure often span multiple independent
Git repositories. `wspace` treats repository families as a synchronized
ecosystem without submodules:

* **Submodules**: Preserves independent Git history, remotes, package managers,
  and release surfaces for every repository.
* **Git worktree isolation**: Isolates feature development into linked worktrees
  (`worktrees/<repo>/<feature>`), preventing dirty state in base checkouts.
* **Conservative operations**: Mutating commands (`update`, `worktree`,
  `env sync`) refuse to rewrite user history, touch dirty repositories, or alter
  unmanaged checkouts.
* **Project agnostic**: Configured via JSON manifest files (`repos.json` or
  custom `--manifest <path>`).

## Repositories and packages

| Package / Repository                                        | Purpose                                 | Distribution                                              |
| ----------------------------------------------------------- | --------------------------------------- | --------------------------------------------------------- |
| [workspace-cli](https://github.com/wazootech/workspace-cli) | Workspace CLI implementation (`wspace`) | [JSR `@wazoo/workspace`](https://jsr.io/@wazoo/workspace) |

## Installation

Install the `wspace` binary using Deno:

<CodeGroup>
  ```sh Deno JSR theme={null}
  deno install -g --name wspace jsr:@wazoo/workspace
  ```

  ```sh From Source theme={null}
  git clone https://github.com/wazootech/workspace-cli.git
  cd workspace-cli
  deno task build
  ```
</CodeGroup>

## Command reference

### `wspace check`

Performs a read-only health check across all manifest-managed repositories and
linked feature worktrees.

```sh theme={null}
wspace check [--json]
```

* Reports status for each repository: `CLEAN`, `DIRTY`, `FEATURE_CLEAN`,
  `DIVERGED`, `UNKNOWN`, `MISSING`, `INVALID`, `PATH_BLOCKED`, or `ERROR`.
* Inspects linked feature worktrees and flags uncommitted work as
  `WORKTREE_DIRTY`.
* Filters directory scans to exclude managed repositories from unmanaged output.
* Exits `0` when clean and `1` when any repository or worktree requires
  attention.

### `wspace init` / `wspace sync`

Clones missing repositories specified in the manifest into the workspace.

```sh theme={null}
wspace init [--json]
```

* Exits non-zero (`1`) if any remote clone fails or collides with a non-Git path
  (`PATH_BLOCKED`).
* Does not reset, overwrite, or clean up existing checkouts.

### `wspace update`

Fetches remotes and fast-forwards clean default branches.

```sh theme={null}
wspace update [--json]
```

* Skips repositories checked out on feature branches (`SKIP_FEATURE`) or
  containing uncommitted changes (`SKIP_DIRTY`).
* Fast-forwards only clean default branches tracking remote branches without
  divergence.

### `wspace worktree add`

Creates a linked Git worktree under `worktrees/<repo>/<feature>` on branch
`<feature>`.

```sh theme={null}
wspace worktree add <repo> <feature> [<commit-ish>]
```

* Start point defaults to `origin/<default>` (resolved via `origin/HEAD`).
* Validates repository and feature names against path traversal (`..`).
* Attaches existing local branches when present.

### `wspace worktree list`

Lists active worktrees across all manifest repositories.

```sh theme={null}
wspace worktree list [--stale] [--json]
```

* With `--stale`, filters to worktrees whose branch is fully merged into the
  default branch (or missing).

### `wspace worktree remove`

Removes a feature worktree and prunes stale Git references.

```sh theme={null}
wspace worktree remove <repo> <feature>
```

### `wspace env sync`

Synchronizes local environment files (`.env`, `.env.*`, `.dev.vars`) from a
`secrets/` vault into checkouts and linked worktrees.

```sh theme={null}
wspace env sync [--dry-run] [--json]
```

* With `--dry-run`, previews file creation and overwrites without modifying
  files.
* Applies owner-only permissions (`0600`) on copied files.
* Rejects destination symlinks.

### `wspace validate`

Validates the manifest schema without touching the filesystem or invoking Git.

```sh theme={null}
wspace validate [--manifest <path>]
```

## Beginner worktree lifecycle

Execute all commands from the workspace root (the directory containing
`repos.json`):

1. **Check status**: `wspace check`
2. **Refresh baselines**: `wspace update`
3. **Create worktree**:
   ```sh theme={null}
   git -C repos/<repo> worktree add "$PWD/worktrees/<repo>/<feature>" -b <feature>
   ```
   Or use `wspace`: `wspace worktree add <repo> <feature>`
4. **Develop**:
   ```sh theme={null}
   cd worktrees/<repo>/<feature>
   # make changes, run tests, commit
   ```
5. **Sync local secrets**: `wspace env sync --dry-run` then `wspace env sync`
6. **Push and create pull request**:
   ```sh theme={null}
   git push -u origin <feature>
   gh pr create
   ```
7. **Find merged worktrees**: `wspace worktree list --stale`
8. **Clean up**: `wspace worktree remove <repo> <feature>`

### Path resolution and worktree location

* **Workspace root anchor**: Relative repository and worktree paths resolve
  relative to the directory containing `workspace.json` (or `wspace.json` /
  `repos.json`), regardless of caller directory.
* **Why `$PWD` is used with `git -C`**: `git -C repos/<repo>` changes Git's
  working directory to `repos/<repo>` before executing. Passing a relative path
  like `worktrees/<repo>/<feature>` would nest the worktree inside
  `repos/<repo>/worktrees/`. Using `"$PWD/worktrees/<repo>/<feature>"` resolves
  `$PWD` from the workspace root before Git runs.
* **Automatic path resolution with `wspace`**: Running
  `wspace worktree add <repo> <feature>` resolves absolute paths under
  `worktrees/<repo>/<feature>` automatically.

### Worktree dependency management

Each Git worktree maintains an independent working directory, while package
managers optimize dependency caching across worktrees:

* **`pnpm`**: Uses a central content-addressable store
  (`~/.local/share/pnpm/store`). Running `pnpm install` in a new worktree
  hard-links dependencies from the central store without duplicating files or
  re-downloading packages.
* **Deno**: Uses the global `DENO_DIR` module cache (`~/.cache/deno` or
  `%LOCALAPPDATA%\deno`), sharing cached dependencies across all worktrees
  zero-copy.
* **npm / yarn**: Running `npm install` or `yarn install` inside a worktree
  installs dependencies for that worktree, fetching packages from the shared
  user HTTP cache.

## Manifest schema

```json theme={null}
{
  "$schema": "https://raw.githubusercontent.com/wazootech/workspace-cli/main/schema/workspace-manifest.schema.json",
  "workspaceRoot": ".",
  "repositoriesDirectory": "repos",
  "worktreesDirectory": "worktrees",
  "vaultDirectory": "secrets",
  "repositories": [
    {
      "name": "workspace-cli",
      "url": "https://github.com/wazootech/workspace-cli.git"
    },
    {
      "name": "worlds-client-ts",
      "url": "https://github.com/wazootech/worlds-client-ts.git"
    },
    {
      "name": "worlds-sdk-ts",
      "url": "https://github.com/wazootech/worlds-sdk-ts.git"
    }
  ]
}
```

Path resolution anchors all relative directories (`workspaceRoot`,
`repositoriesDirectory`, `worktreesDirectory`, `vaultDirectory`) to the folder
containing the manifest file.