Skip to content

Quick Start

GWZ (Git Workspace Zone) coordinates several ordinary Git repositories as one workspace. The root repository records which member repositories belong to the workspace and the exact revisions that make up a reproducible state; each member remains a normal Git repository.

This guide gets you through the first useful workflow. Use the repository lifecycle guide when you need the full identity and recovery rules.

1. Install GWZ

On macOS or Linux:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/owebeeone/gwz-cli/releases/latest/download/gwz-installer.sh | sh

On Windows PowerShell:

powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm https://github.com/owebeeone/gwz-cli/releases/latest/download/gwz-installer.ps1)"

From 1.0.12 you can instead build it from crates.io with Rust 1.95 or newer; on macOS and Linux that also needs the OpenSSL development files:

cargo install gwz

Confirm the installation:

gwz --version
gwz --help

See Install for pinned versions, source installs, and release verification.

2. Choose How To Start

Create A New Workspace

Create an empty Git repository that will own the workspace metadata:

mkdir demo
cd demo
gwz init

Then grow it using the command that matches the repository you have:

Situation Command
The remote repository already exists gwz repo clone <url> [path]
The local Git repository already exists gwz repo add <path>
The repository does not exist yet gwz repo create <path>

Create one new local member for this walkthrough:

gwz repo create services/api
gwz status

In another workspace, the corresponding remote-clone or existing-local-repo forms would be:

gwz repo clone git@github.com:org/shared.git libs/shared
gwz repo add tools/local-helper

Commit the root metadata after checking the result. If a local repository was registered with repo add, explicitly include the manifest:

gwz add gwz.conf
gwz commit -m "Define the workspace"

Two pairs of commands sound similar

  • gwz clone clones an entire workspace root and materializes its members. gwz repo clone adds one member repository to the workspace you are already in.
  • gwz add stages file content across repositories. gwz repo add registers an existing Git repository as a member.

Clone An Existing Workspace

If somebody has already published a GWZ workspace, clone its root and materialize the locked member revisions in one operation:

gwz clone https://github.com/org/workspace.git work/workspace
cd work/workspace
gwz status
gwz ls --local

Manifests record member remotes as URLs, often in the SSH form git@github.com:org/repo.git. That form needs an SSH key. If you have no SSH keys and the repositories are public, ask GWZ for the HTTPS form instead:

gwz clone --url-scheme https git@github.com:org/workspace.git work/workspace

The environment variable does the same thing:

GWZ_URL_SCHEME=https gwz clone git@github.com:org/workspace.git work/workspace

GWZ converts URLs on github.com, gitlab.com, and bitbucket.org. URLs on any other host, and local paths, are used exactly as written. --url-scheme ssh asks for the SSH form the same way. The workspace remembers an ssh or https choice in .gwz/url-scheme.yml, so a later gwz materialize in that workspace needs no flag.

A workspace cloned over HTTPS also publishes over HTTPS: gwz push pushes to the HTTPS remotes and reads the root's member dependencies over HTTPS, with credentials from your Git credential helper. See Publication for what a push checks and how to switch a workspace cloned over SSH.

Contributors with SSH keys need nothing here. The default is manifest, which uses every URL exactly as the manifest records it. A manifest may record either form, and GWZ clones with the form you ask for. A member marked private: true in the manifest that you cannot reach is skipped quietly, whatever scheme is in use, and gwz status then lists it as not materialized.

If the root was cloned with plain git clone, finish it with:

gwz materialize --lock
gwz status

3. Work Across The Repositories

The everyday loop is intentionally Git-like:

gwz status
gwz diff
gwz add path/to/file another/member/file
gwz diff --cached
gwz commit -m "Update the shared API"
gwz log -n 10
gwz status

gwz log shows the root and active member histories as one newest-first workspace stream. Commits created together by gwz commit normally appear as one entry, so the history follows the workspace change rather than repeating the same coordinated commit for every repository. Use gwz log --full for complete commit and member details, or continue with the log command page.

Commands discover the workspace from the current directory, including when run inside a member. Use --root <path> only when you need to override that discovery.

Run the same command in members when a change spans several repositories:

gwz forall -- git status --short
gwz forall gwz-cli gwz-core -- cargo test

Record a named checkpoint before a broad or risky change:

gwz snapshot before-refactor
# Later, if needed:
gwz materialize --snapshot before-refactor

Preview broad mutations before applying them:

gwz --dry-run pull --head
gwz pull --head
gwz push

4. Publish A Member Created Locally

gwz repo create creates a local repository; it does not create a repository on GitHub or another hosting service. When an empty hosted repository is ready, add its origin with Git and synchronize that configuration into the GWZ manifest:

git -C services/api remote add origin git@github.com:org/api.git
gwz repo sync services/api

printf '# API service\n' > services/api/README.md
gwz add services/api/README.md gwz.conf
gwz commit -m "Create API service"
gwz --member mem_api push

repo sync records the observed remote and desired branch. It does not create the hosted repository, fetch, push, change branches, or rewrite the lock. Its manifest change is currently unstaged, so the example explicitly stages gwz.conf. The member needs at least one commit before its first push.

If the hosted repository already contains history that must be preserved, use gwz repo clone instead of this publish-later flow.

5. Detach And Reattach A Member

Detach removes a member from the active composition without deleting its checkout or historical designation:

gwz repo detach mem_shared
gwz repo attach mem_shared

Attach verifies that every commit previously recorded for the member in snapshots and markers exists in the checkout. It fails before changing metadata when that evidence is missing. If no historical commit evidence exists, explicit attach proceeds with a warning because you named the designation; automatic repo add will not infer an identity from empty evidence.

See Repository Member Lifecycle before replacing a member, reattaching a shallow checkout, or reusing a source identity.

Develop GWZ Itself

The gwz-dev workspace is the complete coordinated development checkout:

gwz clone https://github.com/owebeeone/gwz-dev.git gwz-dev
cd gwz-dev
gwz status
cargo test --workspace

Continue with Root Workspaces for the contributor workflow.

Where To Go Next