GWZ Documentation¶
GWZ (Git Workspace Zone) coordinates multiple ordinary Git repositories as one reproducible, inspectable workspace. The workspace root records composition and exact state; member repositories remain normal Git repositories.
New in the 1.0 series: local clones — an isolated second copy
of the whole workspace (a lane) with its own repositories and state, integrated
back by name with gwz merge --remote NAME. On reflink filesystems a lane is
seconds and megabytes, not minutes and gigabytes.
Start with the Quick Start to install gwz, create or clone a
workspace, make a cross-repository change, and learn the repository lifecycle.
Choose A Path¶
| I want to… | Read… |
|---|---|
| Install and use GWZ for the first time | Quick Start |
| Understand what GWZ adds to Git | Why GWZ |
| Add, create, detach, attach, or replace a member | Repository Member Lifecycle |
| Build or change GWZ itself | Root Workspaces |
| Embed the engine or build a remote client | gwz-core documentation |
| Script the CLI | Machine Output and CLI Reference |
| Inspect history across the whole workspace | gwz log |
| Get out of a merge that will not finish or close | Merge Recovery Runbook |
| Work in an isolated copy of the workspace and merge it back by name | Local Clones |
| Let Claude Code start its sessions in a workspace lane | Claude Code |
GWZ resolves the workspace from the current directory, including from inside a
member repository. Use --root <path> only to override that discovery.
Guides¶
- Install: installers, source installs, and release verification.
- Concepts: roots, members, manifests, locks, snapshots, selections, remotes, and progress.
- Workflows: task-oriented multi-repository recipes.
gwz log: one history across the root and member repositories.- Repository Member Lifecycle: clone, create, publish, detach, attach, evidence-backed re-add, and replacement.
- Root Workspaces: work in a GWZ-managed development root.
- Troubleshooting: common failures and recovery.
- Merge Recovery Runbook: refused recovery checkouts, unavailable rollbacks, and an open merge no command can close.
- Local Clones: a second working copy of the whole workspace on the same machine, integrated by name and deleted only when its history provably survives elsewhere.
- Agent Bootstrap: the generated
AGENTS_GWZ.mdhint and standardAGENTS.mdentry point. - Releases: release docs and installer verification.
Reference¶
- CLI Reference: generated root and command help.
- Machine Output: JSON, JSONL, porcelain, and exit codes.
- Command pages: semantics and examples by command.
Terminal help and the generated reference come from the Clap command definitions. Check generated documentation after changing the command surface: