CLI Reference¶
This reference is generated from the Clap command definitions used by the gwz binary.
Do not hand-edit mechanical help content in this file; update the parser/help text and regenerate it.
Regenerate:
Check for drift:
Hosted docs: https://owebeeone.github.io/gwz-cli/
Root Help¶
GWZ (Git Workspace Zone) manages a local workspace made from multiple git repositories.
A workspace records its member repositories and exact revisions under the
tracked `gwz.conf/` directory. Commands operate on the workspace as a whole,
so a single request can initialize, inspect, snapshot, materialize, pull, or
push a coordinated set of repositories.
Documentation: https://owebeeone.github.io/gwz-cli/
Usage: gwz [OPTIONS] <COMMAND>
Commands:
add Stage file contents across workspace repos (multi-repo git add)
branch Manage git branches across workspace members
capture Record the live worktree state into the lock (no mutation)
clone Clone a workspace and materialize its members
commit Commit staged changes across members and the workspace root
diff Show workspace changes as one unified diff (multi-repo git diff)
forall Run a command in selected workspace targets: gwz forall [projects…] -- <cmd> | -c
<string>
init Create a workspace or initialize one from source URLs
ls List workspace targets (id, path; absolute or --local)
materialize Materialize workspace members to a target
pull Update workspace members to an explicit target
push Push workspace target refs
repo Manage workspace repository members
snapshot Record the current workspace selection
stash Manage coordinated git stashes across workspace members
status Show workspace git status
tag Manage git tags across workspace repos (create/list/delete)
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz init git@github.com:org/app.git git@github.com:org/lib.git
gwz status
gwz snapshot before-refactor
gwz pull --head
Documentation: https://owebeeone.github.io/gwz-cli/
Command Help¶
gwz add¶
Command page: add.
Stage file contents across the workspace's member repositories.
`gwz add` is the multi-repo `git add`: each pathspec is resolved relative to the
current directory, routed to the member (or workspace root) repository that owns
it, and staged there. Pair it with `gwz commit`. To register an existing
repository as a workspace member, use `gwz repo add` instead.
Usage: gwz add [OPTIONS] [pathspec]...
Arguments:
[pathspec]...
Paths to stage; resolved relative to the current directory like `git add`
Options:
-A, --all
Stage all changes across every workspace repo (git add -A)
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz add src/main.rs
gwz add gwz-cli/README.md gwz-core/src/lib.rs
gwz add .
gwz add -A
gwz branch¶
Command page: branch.
Manage local Git branches across the workspace's selected member repositories.
The CLI only builds a BranchRequest; validation, repository inspection, locking,
and mutation are handled by gwz-core.
list gwz branch [--list]
create gwz branch --create <name> [--from <ref>] [--switch]
delete gwz branch --delete <name>
merge gwz branch --merge <source-ref>
Usage: gwz branch [OPTIONS]
Options:
--list
List branches across selected workspace members. This is the default branch operation.
--create <name>
Create a branch across selected workspace members
--from <ref>
Start point for --create (default HEAD)
--switch
Switch selected members to the branch after --create
--delete <name>
Delete a branch across selected workspace members
--merge <ref>
Merge a source ref into each selected member's current branch
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz branch list branches
gwz branch --list list branches
gwz branch --create feature/login create from HEAD
gwz branch --create work --from main
gwz branch --create work --switch
gwz branch --delete work
gwz branch --merge feature/source
gwz capture¶
Command page: capture.
Record the live worktree state into the lock (no mutation)
Usage: gwz capture [OPTIONS]
Options:
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
gwz clone¶
Command page: clone.
Clone a GWZ workspace from its root repository URL.
`gwz clone` is the one-shot form of `git clone <url>` followed by
`gwz materialize --lock`. It clones the workspace root repository (the one that
owns the tracked `gwz.conf/` directory) into a target directory, verifies it is
a GWZ workspace, then materializes every member: missing member repositories are
cloned and checked out at the commits recorded in `gwz.conf/gwz.lock.yml`.
If the target directory is omitted, it is derived from the URL.
Usage: gwz clone [OPTIONS] <url> [directory]
Arguments:
<url>
Git URL of the workspace root repository
[directory]
Target directory for the cloned workspace. Defaults to a directory named after the
workspace repository.
Options:
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz clone git@github.com:org/workspace.git
gwz clone git@github.com:org/workspace.git work/demo
If you already ran a plain `git clone` on a workspace root, run
`gwz materialize --lock` inside it to complete the clone instead.
gwz commit¶
Command page: commit.
Commit staged changes across members and the workspace root
Usage: gwz commit [OPTIONS] --message <message>
Options:
-m, --message <message>
Commit message applied to every committed repo
-a, --all
Stage tracked modifications first (git commit -a)
--commit-marker
Create and persist a GWZ commit marker
--no-commit-marker
Disable GWZ commit marker creation for this commit
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
gwz diff¶
Command page: diff.
Show changes across the GWZ workspace as one unified, workspace-relative diff.
`gwz diff` behaves like `git diff` over the whole workspace: it diffs the root
repository and each active member and renders one patch with workspace-relative
paths (e.g. `a/gwz-core/src/lib.rs`), root first, then members in manifest
order.
Revisions, ranges (`A..B`, `A...B`), and `+snapshot` ids are passed to the core
untouched and classified per repository; put literal pathspecs after `--`.
Comparison forms:
gwz diff index vs worktree
gwz diff --cached [<commit>] HEAD (or <commit>) vs index
gwz diff <commit> <commit> vs worktree
gwz diff <a> <b> tree vs tree
gwz diff <a>..<b> tree vs tree
gwz diff <a>...<b> merge-base(a,b) vs b
gwz diff +<snapshot> a captured snapshot vs the worktree
Patch output is paged on a terminal (honoring $GIT_PAGER/$PAGER, then `less`);
piped or machine output is written directly. `--exit-code` exits 1 when there
are differences; `--quiet` suppresses output and implies `--exit-code`.
Usage: gwz diff [OPTIONS] [operand]... [-- <pathspec>...]
Arguments:
[operand]...
Revisions, ranges (A..B, A...B), or +snapshot ids. Classified by core. Put pathspecs after
`--`.
[pathspec]...
Literal pathspecs, resolved relative to the current directory (a leading `+` here is a
path, not a snapshot).
Options:
--cached
Diff the index against HEAD (git diff --cached/--staged)
--merge-base
Use the merge base of the operand and HEAD as the old side
-M, --find-renames [<n>]
Detect renames; optional similarity threshold (e.g. -M90 or -M90%)
--no-renames
Disable rename detection, overriding the default
--stat
Show a diffstat instead of a patch
--numstat
Machine-readable diffstat (added/deleted/path)
--shortstat
Only the summary line of --stat
--summary
Condensed creation/rename/mode summary
--name-only
Show only names of changed files
--name-status
Show names and status of changed files
--raw
Show the diff in raw format
-z
NUL line-terminate name/status/raw records (git diff -z)
-U, --unified <n>
Generate diffs with <n> lines of context
--inter-hunk-context <n>
Show context between nearby hunks, up to <n> lines
--binary
Emit binary patch literals
--text
Treat all files as text
-w
Ignore all whitespace changes
-b
Ignore changes in amount of whitespace
--ignore-space-at-eol
Ignore whitespace changes at end of line
--ignore-blank-lines
Ignore changes whose lines are all blank
--src-prefix <prefix>
Show the given source prefix instead of "a/"
--dst-prefix <prefix>
Show the given destination prefix instead of "b/"
--no-prefix
Do not show any source or destination prefix
--line-prefix <prefix>
Prepend an additional prefix to every line of output
--exit-code
Exit 1 if differences exist, 0 otherwise (like git diff --exit-code)
--quiet
Suppress all output; implies --exit-code
--no-pager
Do not pipe human patch output through a pager
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz diff
gwz diff --cached
gwz diff HEAD
gwz diff main...topic -- gwz-core/src
gwz diff +start-project
gwz diff --stat
gwz diff --name-status
gwz diff --quiet --exit-code
gwz forall¶
Command page: forall.
Run a command in selected workspace targets: gwz forall [projects…] -- <cmd> | -c <string>
Usage: gwz forall [OPTIONS] [projects]... [-- <cmd>...]
Arguments:
[projects]...
Members to run in (id or path); empty = all. Put the command after `--`.
[cmd]...
Command + args, run directly without a shell (portable). Use after `--`.
Options:
-c, --command-string <string>
Run a shell command string (sh -c / cmd /C) instead of an argv
--no-banner
Suppress the per-member `=== <path> ===` banner
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
gwz init¶
Command page: init.
Create a workspace or initialize one from source URLs.
A GWZ workspace is a local directory that owns a tracked `gwz.conf/` metadata
directory. `gwz.conf/gwz.yml` describes the workspace and its repository
members. `gwz.conf/gwz.lock.yml` records the exact revisions that make the
workspace reproducible.
Running `gwz init` with no URLs creates an empty workspace at `--root` or the
current directory. Passing one or more URLs creates the workspace and adds those
repositories as initial members, materialized from their heads.
Running `gwz init --update` refreshes root-only GWZ-managed bootstrap files in
an existing workspace, including `AGENTS_GWZ.md`. Managed files are overwritten
only when their digest header still matches their body; use global `--force` to
replace a locally edited bootstrap file.
Usage: gwz init [OPTIONS] [url]...
Arguments:
[url]...
Git source URL to add as an initial workspace member. May be supplied more than once.
Options:
--update
Refresh GWZ-managed root bootstrap files in the current workspace root, including
AGENTS_GWZ.md. Refuses locally edited files unless global --force is supplied.
--path <path-prefix>
Workspace-relative prefix for initialized source repositories. Defaults to an empty
prefix, so repositories are created directly under the workspace root.
[default: ""]
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz init
gwz --root /work/demo init
gwz init --update
gwz init --path repos git@github.com:org/app.git
gwz init git@github.com:org/app.git git@github.com:org/lib.git
gwz ls¶
Command page: ls.
List workspace targets (id, path; absolute or --local)
Usage: gwz ls [OPTIONS]
Options:
--local
Print workspace-relative paths instead of absolute paths
--unmaterialized
Include configured-but-unmaterialized members
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
gwz materialize¶
Command page: materialize.
Materialize workspace members to an explicit target.
Materialization makes the local repositories match a workspace target. It is not
raw `git pull`; GWZ plans the workspace operation first and applies the selected
target across members. With no target flag, `gwz materialize` uses the workspace
lock. Use `--head`, `--snapshot`, `--tag`, or `--switch` for a different
target.
Usage: gwz materialize [OPTIONS]
Options:
--lock
Materialize the workspace lock. This is the default target.
--head
Materialize repository heads
--snapshot <name>
Materialize a workspace snapshot
--tag <name>
Materialize a workspace tag
--switch <branch>
Switch workspace members to a branch
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz materialize
gwz materialize --lock
gwz materialize --snapshot before-refactor
gwz --force materialize --tag release-2026-06
gwz materialize --switch feature/login
gwz pull¶
Command page: pull.
Move workspace members forward to an explicit target.
`gwz pull` is a workspace operation, not a direct wrapper around `git pull`.
The default target is `--head`, and the default sync policy is fast-forward only.
If any selected member cannot update cleanly, the operation is rejected before
partial mutation unless `--partial` or another explicit policy changes that
behavior.
Usage: gwz pull [OPTIONS]
Options:
--head
Pull repository heads. This is the default target.
--snapshot <name>
Pull a workspace snapshot
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz pull --head
gwz pull --snapshot integration-baseline
gwz --sync fetch-only pull --head
gwz --partial pull --head
gwz push¶
Command page: push.
Push workspace target refs to configured remotes.
`gwz push` applies one push request across selected workspace targets. By
default that includes the workspace root (`@root`) plus configured member
repositories. Use `--remote` to choose a remote name and selectors such as
`--target`, `--member`, `--member-path`, `--all`, and `--no-target @root` to
control which targets participate.
Usage: gwz push [OPTIONS]
Options:
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz push
gwz push --remote origin
gwz --member mem_app push
gwz repo¶
Command page: repo.
Manage repository members inside a workspace.
Repository commands bring member repositories into a workspace and manage their
manifest metadata. Clone or create a new member, add an existing checkout,
detach a designation from the current composition, attach an inactive
designation, or sync metadata from local git config. Use top-level commands
such as `gwz status`, `gwz pull`, and `gwz push` for workspace-wide operations.
Usage: gwz repo [OPTIONS] <COMMAND>
Commands:
add Add an existing git repository as a member
clone Clone and register a new repository member
create Create a new repository member
detach Detach a repository member without deleting its checkout
attach Reattach an inactive repository designation
sync Refresh member metadata from local git config
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz repo clone git@github.com:org/shared-lib.git libs/shared
gwz repo create repos/new-service
gwz repo detach libs/shared
gwz repo attach mem_shared
gwz repo sync gwz-py
gwz help repo create
gwz repo add¶
Command page: repo.
Add an existing local git repository to the workspace.
Use this when a repository already exists on disk and should become a workspace
member. GWZ records the repository as a member; it does not clone a new copy.
Use `gwz repo create` instead when the member should be created from scratch.
Usage: gwz repo add [OPTIONS] <repo-path>
Arguments:
<repo-path>
Path to an existing local git repository
Options:
--member-id <member-id>
Explicit member designation id
--source-id <source-id>
Explicit logical source id
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz repo add repos/app
gwz repo add libs/shared --member-id mem_shared_v2 --source-id src_shared
gwz --root /work/demo repo add /src/local-lib
gwz repo clone¶
Command page: repo.
Clone a Git repository into the current workspace and register it as an active
member.
The optional member path controls where the checkout is created. Without it,
GWZ derives the path from the repository URL. `--member-id` and `--source-id`
override the derived designation and logical source identities. Dry-run plans
the clone without creating the checkout or changing workspace artifacts.
Usage: gwz repo clone [OPTIONS] <url> [member-path]
Arguments:
<url>
Git URL of the repository to clone
[member-path]
Workspace-relative target path; defaults from the URL
Options:
--member-id <member-id>
Explicit member designation id
--source-id <source-id>
Explicit logical source id
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz repo clone git@github.com:org/shared-lib.git
gwz repo clone git@github.com:org/shared-lib.git libs/shared
gwz --dry-run repo clone git@github.com:org/shared-lib.git libs/shared
gwz repo clone git@github.com:org/replacement.git libs/shared --member-id mem_replacement
gwz repo create¶
Command page: repo.
Create a new local repository member and register it with the workspace.
The repository is created immediately at the requested member path and can be
pushed to a remote later. This supports the GWZ workflow where a workspace can
grow new repositories locally before deciding where they should be published.
Usage: gwz repo create [OPTIONS] <member-path>
Arguments:
<member-path>
Workspace-relative path for the new repository member
Options:
--member-id <member-id>
Explicit member designation id
--source-id <source-id>
Explicit logical source id
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz repo create repos/new-service
gwz repo create repos/new-service --member-id mem_service --source-id src_service
gwz --root /work/demo repo create packages/experiment
gwz repo detach¶
Command page: repo.
Stop managing an active member in the current workspace composition.
GWZ marks the manifest designation inactive and removes it from the current
lock. The checkout, snapshots, and markers remain in place. Select exactly one
member by id or workspace-relative path; global selection flags cannot be
combined with the positional member.
Usage: gwz repo detach [OPTIONS] <member>
Arguments:
<member>
Active member id or workspace-relative path
Options:
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz repo detach mem_shared
gwz repo detach libs/shared
gwz --dry-run repo detach libs/shared
gwz repo attach¶
Command page: repo.
Reactivate an inactive repository designation in the current workspace while
preserving its member and source identities.
Attach requires the historical member id and retained checkout. Every
snapshot or marker commit recorded for that member must exist in the checkout.
If no historical evidence exists, explicit attach proceeds with a warning.
Usage: gwz repo attach [OPTIONS] <member-id>
Arguments:
<member-id>
Inactive member designation id
Options:
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz repo detach mem_shared
gwz repo attach mem_shared
gwz --dry-run repo attach mem_shared
gwz repo sync¶
Command page: repo.
Refresh GWZ member metadata from local git config.
`gwz repo sync` reads already-registered, materialized member repositories and
updates the workspace manifest with their configured git remotes and current
desired ref. It does not fetch, push, check out branches, or rewrite the lock.
Usage: gwz repo sync [OPTIONS] [member-path]
Arguments:
[member-path]
Workspace-relative member path to sync
Options:
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz repo sync
gwz repo sync gwz-py
gwz --member-path gwz-py repo sync
gwz --dry-run repo sync gwz-py
gwz snapshot¶
Command page: snapshot.
Record the current workspace selection as a named snapshot.
A snapshot captures the current member revisions so the workspace can later be
materialized back to the same coordinated state. Use snapshots before risky
multi-repository changes, before sharing a reproducible work area, or before
pulling all members forward.
By default, GWZ snapshots the observed selected member heads. Use bare
`--branch` to snapshot each member's current attached branch, or
`--branch <name>` to snapshot a named branch across members.
Usage: gwz snapshot [OPTIONS] [name]
Arguments:
[name]
Snapshot name to record (omit to list existing snapshots)
Options:
--list
List existing snapshots instead of recording one
--branch [<name>]
Snapshot branch heads instead of observed worktree heads. Use bare `--branch` for the
current attached branch, or `--branch <name>` for a named branch.
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz snapshot before-refactor
gwz --all snapshot integration-baseline
gwz snapshot current-branches --branch
gwz snapshot release-line --branch release/2026-06
gwz stash¶
Command page: stash.
Manage coordinated Git stashes across the workspace's selected member repositories.
The CLI only builds a StashRequest; stash discovery, registry I/O, Git operations,
and conflict handling are owned by gwz-core.
push gwz stash push [-u|-a] [-m <message>]
list gwz stash list [--expanded]
apply gwz stash apply [stash-id]
pop gwz stash pop [stash-id]
drop gwz stash drop <stash-id>
Usage: gwz stash [OPTIONS] <COMMAND>
Commands:
push Push a coordinated stash across selected workspace members
list List coordinated stashes
apply Apply a coordinated stash
pop Pop a coordinated stash
drop Drop a coordinated stash
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz stash push
gwz stash push -u -m "wip"
gwz stash push -a
gwz stash list
gwz stash list --expanded
gwz stash apply stash_abc123
gwz stash pop
gwz stash drop stash_abc123
gwz stash push¶
Command page: stash.
Push a coordinated stash across selected workspace members
Usage: gwz stash push [OPTIONS]
Options:
-u
Include untracked files
-a
Include ignored files; the core handler also includes untracked files
-m <message>
Message suffix for the stash
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
gwz stash list¶
Command page: stash.
List coordinated stashes
Usage: gwz stash list [OPTIONS]
Options:
--expanded
Include expanded per-member bundle detail
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
gwz stash apply¶
Command page: stash.
Apply a coordinated stash
Usage: gwz stash apply [OPTIONS] [stash-id]
Arguments:
[stash-id]
Stash id; defaults to latest
Options:
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
gwz stash pop¶
Command page: stash.
Pop a coordinated stash
Usage: gwz stash pop [OPTIONS] [stash-id]
Arguments:
[stash-id]
Stash id; defaults to latest
Options:
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
gwz stash drop¶
Command page: stash.
Drop a coordinated stash
Usage: gwz stash drop [OPTIONS] <stash-id>
Arguments:
<stash-id>
Stash id
Options:
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
gwz status¶
Command page: status.
Show git status across workspace members.
The default mode requests a combined workspace status: file paths are reported
relative to the workspace and prefixed by member path when file entries are
available. Use `--no-combined` for per-member summaries. Use `--porcelain` when
another tool needs stable script-oriented output.
Usage: gwz status [OPTIONS]
Options:
--combined
Render combined workspace status. This is the default mode.
--no-combined
Render per-repo status with file changes instead of one combined workspace view.
--porcelain
Render stable script-oriented output instead of human-readable text.
--no-files
Omit file changes from combined status while keeping branch summaries.
--no-branches
Omit branch summaries from combined status while keeping file changes.
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz status
gwz status --no-combined
gwz status --porcelain
gwz --member mem_app status
gwz tag¶
Command page: tag.
Manage real git tags across the workspace's member repositories — the multi-repo
`git tag`, fanned out the way `gwz commit` fans out `git commit`.
Local operations (create, list, delete) span the selected members plus the workspace
root; remote operations (push, fetch, and list/delete against a --remote) span the
members only.
create gwz tag <name> [-m <message>] [-s] lightweight / annotated / signed
list gwz tag local (or --list [--remote <name>])
delete gwz tag --delete <name> [--remote <name>]
push gwz tag --push [<name>] [--remote <name>] one tag, or every tag
fetch gwz tag --fetch [--remote <name>]
Usage: gwz tag [OPTIONS] [name]
Arguments:
[name]
Tag name (omit to list)
Options:
--list
List tags (the default with no name)
--delete
Delete the named tag
--push
Push tags to a remote (a named tag, or all gwz tags if no name)
--fetch
Fetch gwz tags from a remote
-m <message>
Annotated tag message
-s, --sign
Create a signed tag
-h, --help
Print help (see a summary with '-h')
Global Options:
--root <path>
Workspace root. Defaults to the current directory when not supplied.
--target <selector>
Select a workspace target such as `@root`, `@all`, a member id, or a member path. May be
supplied more than once.
--no-target <selector>
Exclude a workspace target after includes are expanded. May be supplied more than once.
--member <selector>
Compatibility alias for `--target`. Selects a workspace target by selector and may be
supplied more than once.
--no-member <selector>
Compatibility alias for `--no-target`. Excludes a workspace target and may be supplied
more than once.
--member-path <member-path>
Compatibility path selector. Selects a workspace target by member path and may be supplied
more than once.
--no-member-path <member-path>
Compatibility path exclusion. Excludes a workspace target by member path and may be
supplied more than once.
--all
Select all workspace targets (`@all`). May be combined with target exclusions.
--dry-run
Plan the operation without mutating workspace metadata or member repositories.
--partial
Allow operations to complete for members that can proceed even when another selected
member fails.
--force
Allow destructive behavior when required. GWZ refuses destructive changes unless this is
explicit.
--sync <mode>
Select workspace sync behavior. The default policy is fast-forward only.
[possible values: fetch-only, ff-only, merge, rebase, reset, driver-selected]
--remote <name>
Select the git remote name used by operations that contact remotes.
--jobs <n>
Global ceiling on the total number of member repositories processed concurrently across
all hosts. Defaults to 50. Per-host concurrency is bounded separately by --max-per-host.
--max-per-host <n>
Maximum concurrent network operations against a single remote host, so a host is not
overloaded. Members whose host cannot be parsed (e.g. local paths) are bounded only by
--jobs. Defaults to 8.
--progress-interval <ms>
Minimum milliseconds between member progress events per repository. Coalesces
high-frequency Git transfer updates; 0 emits every update. Defaults to 100.
--json
Render one structured JSON response for the operation.
--jsonl
Render newline-delimited JSON records for streaming operation consumers.
--ssh-timeout <secs>
Maximum seconds to wait on a stalled SSH/network read before failing. libssh2 has no
timeout by default, so a missing ssh-agent identity or an unreachable host would otherwise
hang forever. 0 disables the timeout. Defaults to 3.
Examples:
gwz tag v1 create v1 across members (and the committed root)
gwz tag v1 -m "release one" annotated tag
gwz tag list local tags
gwz tag --delete v1 delete v1 locally
gwz tag --push v1 push v1 to each member's remote
gwz tag --push push every tag
gwz tag --fetch fetch tags from each member's remote
gwz tag --list --remote origin list tags on a remote
gwz materialize --tag v1 check out each member's refs/tags/v1