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 — manage a workspace of Git repositories
Usage: gwz [OPTIONS] <COMMAND>
Inspect: status ls diff log fetch
Change: add commit branch tag stash merge pull push
Workspace: init clone snapshot capture materialize
Members: repo add|create|clone|detach|attach|sync
Lanes: local clone|list|dispose|disband hook claude-code
Other: auth forall
Selection (default: root and every member):
--root PATH Workspace to operate in (default: current directory)
--target TARGET Repositories to include: @root, @all, member ID or path
--no-target TARGET Repositories to exclude
--remote NAME Git remote for network operations; local lane for merge
Common options:
--json Structured output; try gwz --json help [COMMAND...]
--verbose Authentication diagnostics
--dry-run Preview where supported; some commands refuse it
-h, --help Show help
-V, --version Show version; --build-info adds source identity
Details and all options: gwz help COMMAND [SUBCOMMAND]
Example: gwz --root ROOT --target @all merge --remote LANE
Receive LANE's root and member histories into ROOT.
Documentation: https://owebeeone.github.io/gwz-cli/
Command Help¶
gwz auth¶
Manage local SSH identity configuration
Usage: gwz auth [OPTIONS] <COMMAND>
Commands:
identity Read or change a remote's local key path for selected repositories
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 auth identity¶
Read or change a remote's local key path for selected repositories
Usage: gwz auth identity [OPTIONS] <REMOTE>
Arguments:
<REMOTE>
Options:
--set <PATH>
--unset
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 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.
A target selection (`--target`/`--member`/`--path`) scopes the staging. With
`-A` it stages the selected targets only. With pathspecs it constrains routing:
a pathspec that names a repository outside the selection is an error, and
repositories reached only by `.` fan-out are skipped. `--dry-run` validates the
routing and stages nothing.
Usage: gwz add [OPTIONS] [pathspec]...
Arguments:
[pathspec]...
Paths to stage; resolved relative to the current directory like `git add`
Options:
-A
Stage all changes across every workspace repo (git add -A). `--all` is the target
selector.
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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> deprecated alias for gwz merge
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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 deprecated; use gwz 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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 a URL.
`gwz clone <url>` 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.
Manifests may record member remotes in the ssh form (`git@github.com:...`) or
the https form. `--url-scheme https` (or `GWZ_URL_SCHEME=https`) clones every
github.com, gitlab.com and bitbucket.org repository over https instead, for a
reader without SSH keys; `--url-scheme ssh` asks for the ssh form. The default,
`manifest`, uses each URL as written, so a contributor with SSH keys needs
nothing. The choice is remembered in `.gwz/url-scheme.yml` for later
`gwz materialize` runs in that workspace.
Usage: gwz clone <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:
--url-scheme <scheme>
URL form used for every repository this run clones on github.com, gitlab.com or
bitbucket.org. `manifest` (the default) uses each URL exactly as the manifest records it;
`https` and `ssh` convert known-host URLs to that form before cloning. URLs on other hosts
and local paths are used as written, and a member that is already checked out keeps its
remotes. The environment variable GWZ_URL_SCHEME is an alternative to the flag; the flag
wins. An `ssh` or `https` choice is remembered in <workspace>/.gwz/url-scheme.yml, so a
later `gwz materialize` needs no flag; an explicit `manifest` clears it.
[possible values: manifest, ssh, https]
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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
gwz clone --url-scheme https git@github.com:org/workspace.git
GWZ_URL_SCHEME=https gwz clone https://github.com/org/workspace.git
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 the selected targets (root included only when selected; default
selection includes the root and every member)
Usage: gwz commit [OPTIONS] --message <message>
Options:
-m, --message <message>
Commit message applied to every committed repo
-a
Stage tracked modifications first (git commit -a). `--all` is the target selector.
--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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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
gwz diff --tagged <a> <b> only repositories containing both local tags
`--tagged` treats every comparison endpoint as an exact local tag and narrows
the normal selected target set to repositories containing all of them. It is
useful when release tags exist in only some workspace repositories.
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
--tagged
Select only repositories containing every supplied local tag
-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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 fetch¶
Contact every selected repository's remote and report what moved.
`gwz fetch` fetches the configured remote of each selected workspace target,
updates that repository's remote-tracking refs, and reports one line per
repository: the tracking ref before and after, how far the current branch is
ahead of and behind it, or `no change`. By default that includes the workspace
root (`@root`) plus configured member repositories, and the selectors are
`push`'s: `--target`, `--member`, `--member-path`, `--all`, `--no-target @root`.
What it does NOT do:
- It never integrates. No merge, no rebase, no fast-forward, no reset: no
branch, no HEAD, no index and no working-tree file changes. Use `gwz pull`
to integrate what a fetch showed you.
- It never writes workspace artifacts: no lock, no manifest, no boundary
sync. Because of that it is one of the few network verbs that still runs
while a merge is open.
- It never prunes.
It always contacts the remotes. There is no `--check-remotes` and no
`unchanged since the last fetch` short-circuit as there is on `gwz push`: a
fetch that does not connect has answered nothing.
`--dry-run` is the one exception, and it is not git's. `git fetch --dry-run`
contacts the remote and then declines to write the refs; `gwz --dry-run fetch`
contacts no remote at all. It resolves the selection and prints the planned
rows, one per repository it would have contacted, and stops there. So it
answers `which repositories would be contacted` and never `what moved`: the
rows carry no result from any remote.
A planned row says so in its own words. It reads `would contact <remote>`, and
its machine result is `Planned`, which a live fetch never produces. `no change`
and `Unchanged` keep their one meaning: the repository WAS contacted and its
tracking ref did not move. A repository with no fetch remote is still `no
upstream` under `--dry-run`, because that answer needs no network.
Exit codes follow `gwz push`: 0 when every selected repository answered,
1 when some answered and some failed (the report is incomplete), and 2 when
every selected repository was refused before the network, for example a
`--remote <name>` that no selected repository has. A dry run exits with the
same codes as the live run it rehearses, and refuses a `--remote` name a
repository lacks just as the live run does.
Usage: gwz fetch [OPTIONS]
Options:
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 fetch
gwz --no-target @root fetch
gwz --member mem_app fetch
gwz --remote upstream fetch
gwz --json fetch
gwz --dry-run fetch
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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 hook¶
Command page: hook.
Serve another tool's hooks for the workspace a session starts in.
A hook command reads the calling tool's JSON payload on standard input, does
the work the tool asked for, and answers on standard output in the shape that
tool documents. Hooks are meant to be run by the tool, not by hand; running one
by hand is still useful for a probe, and every hook reads its input the same
way whoever calls it.
Today one family is served: `gwz hook claude-code`.
Usage: gwz hook [OPTIONS] <COMMAND>
Commands:
claude-code Serve Claude Code's worktree hooks for the workspace a session starts in
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 hook claude-code¶
Command page: hook.
Serve Claude Code's WorktreeCreate and WorktreeRemove hooks, and write the
settings block that installs them.
Claude Code creates a git worktree of the project when a session asks for an
isolated working copy. In a GWZ workspace the members are separate
repositories, git-ignored by the root, so such a worktree has no members and
nothing builds in it. These commands replace that default: a GWZ workspace
gets a local clone of the whole workspace (`gwz local clone`), and any other
project gets the plain git worktree Claude Code would have made.
worktree-create prints only a path it created or verified in this invocation.
worktree-remove deletes only the lane or worktree that `worktree_path`
canonically names. Nothing else is ever printed, and nothing else is ever
deleted. Every failure is one line on standard error, `gwz: <cause>; <remedy>`,
and a non-zero exit with nothing on standard output.
setup writes the settings block with --write and takes it back out with
--remove.
Usage: gwz hook claude-code [OPTIONS] <COMMAND>
Commands:
worktree-create Create or verify the working copy Claude Code asked for, and print its path
worktree-remove Retire the lane or worktree that `worktree_path` names
setup Print the Claude Code hooks block, and with --write or --remove edit a settings
file
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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.
Each hook logs one line per decision: to `<root>/.gwz/claude-hooks.log` in a
workspace, and to `~/.claude/gwz-lane-hooks.log` otherwise, or wherever --log
names. A location that would appear in `git status` is never used.
gwz hook claude-code worktree-create¶
Command page: hook.
Create or verify the working copy Claude Code asked for, and print its path.
Reads Claude Code's WorktreeCreate payload on standard input and takes `name`
and `session_id` from it. The name is validated as a slug of [A-Za-z0-9._-]
that is not a name GWZ reserves.
In a GWZ workspace the result is a local clone of the workspace at
`../<root-dirname>-<name>`, created in process, and the printed path is that
lane — or, when the session started inside a member, that member's directory
inside the lane. An existing lane of the same name is reused only when it is
ready, sits at that destination, belongs to this session and passes the
completeness check; every other state is refused with its own remedy.
Two guards protect the copy: free space against a run-time estimate of what
the copy costs (a walk of the source, a block-sharing probe at the
destination's parent, and a pessimistic share by filesystem), with
--min-free-gb as a floor on top of it; and a ceiling on how many ready lanes
the family may hold. Neither applies to a reuse, which consumes nothing.
Outside a workspace the hook reproduces Claude Code's own default: a worktree
under `.claude/worktrees/<name>` on branch `worktree-<name>`, from
`origin/<default-branch>` when it resolves and `HEAD` otherwise, with the
`.worktreeinclude` copy performed for a worktree this invocation created.
Usage: gwz hook claude-code worktree-create [OPTIONS]
Options:
--min-free-gb <gb>
Refuse a creation when free space on the filesystem holding the destination's parent is
below this many gigabytes. It is a floor applied on top of the copy-cost estimate, never a
replacement for it. Default: no floor, so only the estimate applies.
--max-lanes <n>
Refuse a creation once the family holds this many ready lanes (default 8)
--wait-secs <secs>
Deadline for the attempt loop (default 300)
--base-ref <ref>
Base for the fallback git worktree (default origin/<default-branch>, else HEAD)
--log <path>
Write the hook log here instead of the fixed location
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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:
echo '{"name":"fix-123","session_id":"abc"}' | gwz hook claude-code worktree-create
gwz hook claude-code worktree-remove¶
Command page: hook.
Retire the lane or worktree that `worktree_path` names.
Reads Claude Code's WorktreeRemove payload on standard input, canonicalises
`worktree_path` and classifies it. A registered git worktree of the project is
removed with `git worktree remove`, never with --force, so a dirty or locked
worktree keeps the session. A lane root, or a member directory inside one, is
resolved to its family and disposed with `gwz local dispose`, never with
--keep and never with --force: a hazard refusal keeps the lane and the session,
which is the safe outcome. A path that no longer exists exits zero. Anything
else is refused.
Removal consumes nothing, so none of the copy guards apply here: this leaf
carries only --wait-secs and --log.
Usage: gwz hook claude-code worktree-remove [OPTIONS]
Options:
--wait-secs <secs>
Deadline for the family lock (default 300)
--log <path>
Write the hook log here instead of the fixed location
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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:
echo '{"worktree_path":"/path/to/lane"}' | gwz hook claude-code worktree-remove
gwz hook claude-code setup¶
Command page: hook.
Print the Claude Code hooks block, and with --write or --remove edit a
settings file.
One placement flag is required: --project for the workspace root's
`.claude/settings.json`, --project --local for its `settings.local.json`, or
--user for `~/.claude/settings.json`.
The block carries one WorktreeCreate handler and one WorktreeRemove handler,
each with its own timeout. Inside a workspace the timeouts and the handlers'
--wait-secs are computed from the same run-time estimate the create hook uses;
outside one they are the compiled-in defaults. --wait-secs is written onto a
handler only when the estimate raises the wait above the compiled-in 300 s, so
a small workspace's block carries no --wait-secs at all: its absence means the
300 s default stands, not that no estimate ran. The remove handler carries only
the options that leaf obeys.
The default handler is the bare command `gwz hook ...`, resolved through PATH,
so a committed project block is machine-independent and identical everywhere,
which is what Claude Code's same-handler dedupe keys on. --command pins an
absolute binary instead, for a machine whose desktop app cannot see `gwz` on
its PATH.
--write and --remove are the lifecycle pair, and are refused together.
--write edits another program's configuration, so it parses the existing file
first and refuses one that does not parse, is a symbolic link or is not a
regular file; writes a temporary file beside the target, fsyncs it, re-parses
it and renames it over the original; changes no byte outside the inserted
block; creates the file when it is absent; and does nothing when the block is
already there.
--remove takes the two entries this tool wrote back out, with the same
discipline and the same refusals. It changes no byte outside the removed
entries, drops a WorktreeCreate or WorktreeRemove array or a `hooks` object
left empty behind them, never deletes the file itself, and says so and changes
nothing when the file does not carry the block.
Usage: gwz hook claude-code setup <--project [--local] | --user> [--write | --remove] [OPTIONS]
Options:
--project
Use the workspace root's .claude/settings.json
--user
Use ~/.claude/settings.json
--local
With --project, use settings.local.json instead
--write
Merge the block into the file; without it the block is only printed
--remove
Take the block back out of the file; the file itself is never deleted
--command <PATH>
Pin an absolute gwz binary in the handler instead of the bare `gwz`
--min-free-gb <gb>
Refuse a creation when free space on the filesystem holding the destination's parent is
below this many gigabytes. It is a floor applied on top of the copy-cost estimate, never a
replacement for it. Default: no floor, so only the estimate applies.
--max-lanes <n>
Refuse a creation once the family holds this many ready lanes (default 8)
--wait-secs <secs>
Deadline for the attempt loop (default 300)
--base-ref <ref>
Base for the fallback git worktree (default origin/<default-branch>, else HEAD)
--log <path>
Write the hook log here instead of the fixed location
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 hook claude-code setup --project
gwz hook claude-code setup --project --local --write
gwz hook claude-code setup --user --write --command /usr/local/bin/gwz
gwz hook claude-code setup --project --local --remove
Getting a session into a lane: after --write, run `claude --worktree <name>`
from the workspace root (or start a background session); the lane appears in
`gwz local list` with the session id as its owner; integrate it with
`gwz --target @all merge --remote <name>` from the main workspace, then
`gwz local dispose <name>`.
Install or refresh the agent skill too: copy `skills/gwz/SKILL.md` to
`~/.claude/skills/gwz/`.
One placement is the recommendation. Two placements are harmless when the
handler text is identical, because Claude Code runs an identical handler once;
two differing handlers both run, and a refusal by either orphans the lane the
other created.
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`, and ensures that `AGENTS.md`
points agents to it. Existing `AGENTS.md` instructions are preserved. Managed
files are overwritten only when their digest header still matches their body;
use global `--force` to replace a locally edited bootstrap file.
To deliberately accept edited configuration and commit the recovery together,
run `gwz init --update --force --commit`. Both configuration documents must
parse; this accepts their bytes but does not repair incorrect paths or topology.
The commit includes the manifest, existing lock, integrity marker, managed
instructions and agent-reference/settings files changed by this update.
Unrelated staged work is preserved. `--commit` requires `--update`; omit
`--force` when no hand edit needs acceptance. Unchanged updates make no empty
commit, and `--dry-run` changes nothing. Output names the commit and paths.
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, and ensure AGENTS.md points agents to it. Existing AGENTS.md instructions
are preserved. Refuses locally edited managed files unless global --force is supplied.
--commit
Commit accepted configuration and updated bootstrap files, preserving unrelated staged
work
--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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 local¶
Command page: local.
Create, inspect and retire the local clone family of this workspace.
A local clone is a second working copy of the whole workspace on the same
machine, made with `gwz local clone <name> [dest]`. The family index lives on
the workspace root; every clone carries a pointer back to it, so these commands
work from any ready member of the family.
`gwz local clone` creates a member. `gwz local list` reports the family.
`gwz local dispose` removes one member — its tree, or only its registration
with `--keep`. `gwz local disband` retires the family itself and leaves every
directory in place.
Usage: gwz local [OPTIONS] <COMMAND>
Commands:
clone Create a local clone of this workspace as a new family member
list List the local clone family recorded on the workspace root
dispose Dispose of a local family member, or detach it with --keep
disband Retire the family: remove pointers and the index; every tree stays
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 local clone A ../gwz-dev-A
gwz local list
gwz local dispose C --keep
gwz local dispose C --force open-merge,dirty,unpreserved-history
gwz local disband
gwz local clone¶
Command page: local.
Create a local clone of this workspace as a new family member.
Copies the current workspace into a second working copy on this machine and
registers it, by name, in the local clone family. Integrate work from the
receiving workspace with `gwz merge --remote <name>`. Family pull and push are not supported
by this build. There is no URL and no network. The destination defaults to
`../<root-dirname>-<name>`.
Only verbatim cloning is supported: it copies the source tree as it sits,
dirt and build directories included. The parser accepts --clean, --bare,
-b and --from, but this build refuses those forms before copying.
Keep the source quiet for the whole invocation.
A tool that makes lanes unattended has two options of its own. --owner
<token> records an opaque caller token on the new member row, written by the
same index write that reserves the row, reported by `gwz local list`, never
changed afterwards and never interpreted by GWZ. --wait <secs> keeps
retrying a busy family lock until the deadline, so two invocations fired for
one request queue instead of refusing each other; the one that waits rereads
the family before acting, so it is answered by the lane the other one
made.
Usage: gwz local clone <name> [dest] [--owner <token>] [--wait <secs>]
Arguments:
<name>
Family member name for the new clone. `root`, `origin` and Git's reserved ref names are
not accepted, and a name already recorded in the family is refused.
[dest]
Destination directory of the new clone. Defaults to `../<root-dirname>-<name>` beside the
workspace root. A nonempty directory, a directory that is already a workspace, and a path
inside any family member are refused.
Options:
--verbatim
Copy the source tree as it sits, including staged edits, unstaged edits, untracked files
and build directories. This is the default mode. It is refused while the source has an
open coordinated merge. Mutually exclusive with --clean and --bare.
--clean
Unsupported in this build; parsed but refused before copying. Check out the frozen source
state in the destination: no worktree or index dirt is inherited, and no build directories
are copied. Mutually exclusive with --verbatim.
--bare
Unsupported in this build; parsed but refused before copying. Create the destination as a
share point: the same workspace layout, with every member repository bare. Implies
--clean. Verbs that need a worktree refuse there; push, fetch, log, `gwz local list` and
dispose work.
-b <branch>
Unsupported in this build; parsed but refused before copying. Create this branch in every
destination repository at the frozen commit, before the clone is marked ready. Accepted
only with --clean or --bare. If the branch already exists in any member, the whole create
is refused.
--from <name|path>
Unsupported in this build; parsed but refused before copying. Copy from this family member
or path instead of the current workspace. Accepts a family name recorded in the index or a
filesystem path. Core resolves the token, and refuses one that names no readable source.
The new clone is registered on the workspace root whichever member it was copied from.
--owner <token>
Record this opaque token on the new member's row, in the same index write that reserves
the row. Up to 128 bytes of `[A-Za-z0-9._:-]`. It is the caller's own identity for the
caller's own reuse decisions: GWZ stores it, reports it in `gwz local list` (a column, and
an `owner` field under --json), and never interprets, matches or acts on it. A row created
without --owner records none, and no later command ever sets, changes or clears a row's
token. Recording one makes the family index format 2, which gwz 1.0.14 and later read; an
older gwz refuses the whole index and says so.
--wait <secs>
Seconds to keep retrying a busy family lock before reporting it busy. The family lock is
held for the whole of a create, a dispose or a disband, so two unattended invocations
fired for one request would otherwise refuse each other outright. GWZ retries the try-lock
at a short fixed interval until the deadline; there is no blocking acquisition, so the
wait stays portable and is bounded by the number you give. Omit it and a busy lock refuses
immediately, exactly as before. A wait that wins the lock rereads the index before acting,
so a create that waited behind another create of the same name is answered by the family
that create left, not by a stale view.
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 local clone A ../gwz-dev-A
gwz local clone A --owner claude-code:session_7 --wait 120
`root`, `origin` and Git's reserved ref names are refused as member names, and
so is a name already recorded in the family. A verbatim copy is refused while
the source has an open coordinated merge: finish or abort it first.
--clean, --bare, -b and --from are reserved and unsupported in this build.
--owner <token> takes up to 128 bytes of [A-Za-z0-9._:-] and is recorded on
the row, reported, and never interpreted. --wait <secs> retries a busy family
lock until the deadline. The first index write by a gwz that supports --owner
makes the family index format 2, which gwz 1.0.14 and later read.
gwz local list¶
Command page: local.
List the local clone family recorded on the workspace root.
Reads the index through this workspace's family pointer and reports every
member: its name, kind (checkout or bare), state, and path — the root first,
then every member in name order.
The state column carries both what the index recorded (creating, ready,
disposing) and what was observed on disk (ready, incomplete,
interrupted_disposal, missing, pointer_removed, mismatched, malformed,
unobserved). They are shown as one word while they agree and as
`recorded/observed` when they do not, so an interrupted create or an
interrupted disposal is visible without a second command. Any diagnostic the
index recorded for a member is shown beside its row.
An `owner` column appears when any member records the opaque token a
`gwz local clone --owner <token>` wrote; rows without one show `-`. A family
in which nobody recorded a token renders the four columns above unchanged.
The listing performs no repair and takes no lock; --json and --jsonl carry
every field of every row, `owner` included (null when the row records
none). There is no --wait here, because there is no lock to wait for.
Usage: gwz local list [OPTIONS]
Options:
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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.
Example:
gwz local list
gwz local list --json
Output columns: name, kind, state, path, plus owner when any member records
one and last_error when any member carries one. The state column is one word while
the recorded row and the directory agree, and `recorded/observed` when they do
not — `creating/incomplete` for an interrupted create, for instance. A member
that recorded a diagnostic gets a fifth column carrying it.
gwz local dispose¶
Command page: local.
Dispose of one local family member.
By default this deletes the member's directory, and it refuses to do so while
any hazard is detected: an open coordinated merge, uncommitted or untracked
work, or history that is not verifiably preserved in another surviving family
member. A clean working tree is not preservation proof, and network-only
preservation is not certified.
Each reported hazard must be named explicitly with `--force` before the
deletion proceeds. That is an operator loss waiver, not crash recovery: an
incomplete or interrupted member is retained rather than force-deleted.
`--keep` is the non-destructive alternative: it removes only the pointer and
the index row, so the tree, its open merge and its history stay on disk and
remain usable as an ordinary workspace.
`--wait <secs>` keeps retrying a busy family lock until the deadline instead
of refusing at once.
The workspace root is never disposed, and neither is the member you are
standing in.
Usage: gwz local dispose <name> [--keep] [--wait <secs>]
gwz local dispose <name> --force <hazard,...> [--wait <secs>]
Arguments:
<name>
Family member name recorded in the index
[hazard,...]...
Deletion hazards this disposal is authorized to waive, comma-separated, and accepted only
together with --force. GWZ refuses to delete a member whose work or history is not
verifiably preserved elsewhere; every hazard it reports must be named here before it will.
Known names: open-merge, dirty, unpreserved-history. This is an operator loss waiver, not
crash recovery, and it is mutually exclusive with --keep.
Options:
--keep
Detach only: remove the pointer and the index row. The member's entire tree, its open
merge and its history stay on disk and remain usable as an ordinary workspace. Mutually
exclusive with --force.
--wait <secs>
Seconds to keep retrying a busy family lock before reporting it busy. The family lock is
held for the whole of a create, a dispose or a disband, so two unattended invocations
fired for one request would otherwise refuse each other outright. GWZ retries the try-lock
at a short fixed interval until the deadline; there is no blocking acquisition, so the
wait stays portable and is bounded by the number you give. Omit it and a busy lock refuses
immediately, exactly as before. A wait that wins the lock rereads the index before acting,
so a create that waited behind another create of the same name is answered by the family
that create left, not by a stale view.
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 local dispose C
gwz local dispose C --keep
gwz local dispose C --keep --wait 60
gwz local dispose C --force unpreserved-history
gwz local dispose C --force open-merge,dirty,unpreserved-history
Hazard names: open-merge, dirty, unpreserved-history. They are operands of
this command and are accepted only together with --force; `--force` with no
names is refused, and so is `--keep` together with `--force`.
gwz local disband¶
Command page: local.
Retire the local clone family.
Removes the family pointers and the index only. Every member directory stays
exactly where it is and remains an ordinary GWZ workspace. Family names stop
resolving afterwards, so `--remote <name>` on pull, push and merge falls back
to ordinary Git remote resolution.
Disband may be repeated after an error; it never routes a remaining row through
directory deletion. `--wait <secs>` keeps retrying a busy family lock until
the deadline instead of refusing at once.
Usage: gwz local disband [OPTIONS]
Options:
--wait <secs>
Seconds to keep retrying a busy family lock before reporting it busy. The family lock is
held for the whole of a create, a dispose or a disband, so two unattended invocations
fired for one request would otherwise refuse each other outright. GWZ retries the try-lock
at a short fixed interval until the deadline; there is no blocking acquisition, so the
wait stays portable and is bounded by the number you give. Omit it and a busy lock refuses
immediately, exactly as before. A wait that wins the lock rereads the index before acting,
so a create that waited behind another create of the same name is answered by the family
that create left, not by a stale view.
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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.
Example:
gwz local disband
Every member directory survives; only the pointers and the index are removed.
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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 log¶
Command page: log.
Show local commit history from the workspace root and selected members as one
newest-first stream. Coordinated workspace commits may appear as one entry
attributed to several repositories.
The default compact form is `<date> <member-set> <short-hash> <subject>`.
Small member sets show their workspace-relative member paths; larger sets use
a count such as `[root+5]`. `--full` uses git-style blocks with a complete
member table. `--body` includes commit bodies in full blocks.
Members that cannot contribute are summarized on stderr while surviving
history remains on stdout. `--strict` promotes any such degradation to a
failure. Dates use each commit's recorded offset, and human text is rendered
lossily with terminal control characters sanitized.
Output does not use a pager. `--color=auto` enables ANSI color only when
stdout is a terminal; use `always` or `never` to override.
Usage: gwz log [OPTIONS] [operand]... [-- <pathspec>...]
Arguments:
[operand]...
Revisions, ranges, or +snapshot ids; classified by core. Put pathspecs after `--`.
[pathspec]...
Literal pathspecs relative to the invocation directory
Options:
-n <n>
Limit the global result to N entries (0 disables the limit)
--no-limit
Disable the global result limit
--since <time>
Include commits at or after TIME (RFC3339/ISO-8601; date-only is local midnight,
offset-less is local, or use @epoch-seconds)
--until <time>
Include commits at or before TIME (RFC3339/ISO-8601; date-only is local midnight,
offset-less is local, or use @epoch-seconds)
--author <regex>
Match a case-sensitive Rust regex (not Git regex syntax) against `Name <email>`
--grep <regex>
Match a case-sensitive Rust regex (not Git regex syntax) against the full raw commit
message
--no-merges
Exclude merge commits before workspace coalescing
--first-parent
Follow only each commit's first parent
--strict
Promote any selected-repository degradation to failure
--no-coalesce
Disable workspace-level commit coalescing
--body
Include commit message bodies in --full and machine output
--full
Render git-style blocks with a complete member table
--tagged
Select only repositories containing every supplied local tag
--color <when>
Colorize output: always, never, or auto
[default: auto]
[possible values: always, never, auto]
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 log
gwz log --full --body
gwz log -n 20 --author 'Ada <ada@example.com>'
gwz log --since 2026-08-01T00:00:00Z
gwz log main..topic -- src
gwz --target mem_api log +release..HEAD
gwz log --strict --tagged v0.11.1
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.
`--url-scheme <manifest|ssh|https>` (or `GWZ_URL_SCHEME`) chooses the URL form
for known-host repositories this run clones; members already checked out keep
their remotes. Without it, a preference recorded by an earlier run in
`.gwz/url-scheme.yml` applies, then the manifest as written.
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
--url-scheme <scheme>
URL form used for every repository this run clones on github.com, gitlab.com or
bitbucket.org. `manifest` (the default) uses each URL exactly as the manifest records it;
`https` and `ssh` convert known-host URLs to that form before cloning. URLs on other hosts
and local paths are used as written, and a member that is already checked out keeps its
remotes. The environment variable GWZ_URL_SCHEME is an alternative to the flag; the flag
wins. An `ssh` or `https` choice is remembered in <workspace>/.gwz/url-scheme.yml, so a
later `gwz materialize` needs no flag; an explicit `manifest` clears it.
[possible values: manifest, ssh, https]
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 --lock --url-scheme https
gwz materialize --snapshot before-refactor
gwz --force materialize --tag release-2026-06
gwz materialize --switch feature/login
gwz merge¶
Command page: merge.
Merge a source ref across selected workspace repositories
Usage: gwz merge [source] [--dry-run] [--ff-only] [--no-ff] [--filesystem-strict] [-m <message>]
gwz merge --remote <name> [<ref>] [--wait <secs>]
gwz merge --status [merge-id]
gwz merge --continue
gwz merge --abort [--preserve]
gwz merge --gc [merge-id]
Arguments:
[source]
Source ref resolved independently in each selected repository
Options:
--continue
Continue the open coordinated merge after resolving conflicts
--abort
Safely roll back the open coordinated merge
--status [<merge-id>]
Inspect the open merge, or a retained closed merge by id
--preserve
With --abort, preserve safe post-merge commits and local changes
--gc [<merge-id>]
Apply retention, or remove one retained merge and its backup refs
--ff-only
Require every selected repository to merge by fast-forward
--no-ff
Always create a merge commit, even when a fast-forward is possible
--filesystem-strict
Refuse to merge when crash recovery is unsupported on this filesystem
-m, --message <message>
Use a custom merge commit-message body
--wait <secs>
Seconds to keep retrying a busy family lock before reporting it busy, accepted only with
--remote <name>. A family merge holds the family lock across the import and the merge
itself, so an unattended merge fired while a create, a dispose or another family merge is
running would otherwise refuse outright. GWZ retries the try-lock at a short fixed
interval until the deadline; there is no blocking acquisition, so the wait stays portable
and is bounded by the number you give. Omit it, or pass 0, and a busy lock refuses
immediately, exactly as before. A wait that wins the lock rereads the family index before
it resolves the source, so a merge that waited behind a create or a dispose is answered by
the family that operation left, not by a stale view. An ordinary merge takes no family
lock, so `--wait` without `--remote` is refused rather than accepted and ignored.
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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.
Publication:
- Root dependencies are proven by this operation's own reads or accepted
pushes, never by remote-tracking refs.
- By default, repositories unchanged since the last fetch or push are not
checked for changes or pushed; human output counts them in one summary
line, and `--verbose` shows each reason. A push that contacts the root
still reads each dependency.
- `--check-remotes` reads every selected remote and every root dependency,
pushes repositories whose remote lacks their branch's commit, and proves
a selected root even when it has nothing to push.
Usage: gwz push [OPTIONS]
Options:
--check-remotes
Read every selected remote and every root dependency instead of skipping repositories that
are unchanged since the last fetch or push. Repositories whose remote lacks their branch's
commit are pushed, and a selected root is proven against its committed lock even when it
has nothing to push.
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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 push --check-remotes
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. `--root` selects the
workspace; it does not make relative repository operands relative to that root.
Relative operands stay relative to the directory where `gwz` was invoked, and
`--target` limits participating repositories without changing that path base.
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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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.
The repository path is resolved relative to the directory where `gwz` was
invoked. `--root` selects the workspace and does not change that path base;
`--target` selects participating repositories for workspace operations and does
not change operand resolution. 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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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. A supplied `--root` selects the workspace and does not change the
base for a relative member path; that path remains relative to the invocation
directory. `--target` likewise selects participating repositories without
changing operand path resolution. It does not fetch, push, check out branches,
or rewrite the lock.
A configured remote that differs from the manifest only by URL scheme on
github.com, gitlab.com or bitbucket.org (the mark of a `--url-scheme` clone)
keeps the recorded URL and is reported instead; pass `--force` to record the
configured form.
Usage: gwz repo sync [OPTIONS] [member-path]
Arguments:
[member-path]
Workspace-relative member path to sync
Options:
--private
Quietly skip access refusals when cloning this member in a workspace
--public
Report clone access failures normally for this member
-h, --help
Print help (see a summary with '-h')
Global Options:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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:
--identity <PATH>
Use only this SSH private-key file; no agent fallback
--remote-identity <NAME=PATH>
Override SSH identity for this remote name across selected repositories; repeatable
--root <path>
Workspace root. Defaults to the current directory when not supplied. This selects the
workspace for the operation; it does not change the base directory for relative operands.
Relative paths remain relative to the directory where gwz was invoked.
--target <selector>
Select repositories such as `@root`, `@all`, a member id, or a member path. This limits
which repositories participate; it does not change the base directory for relative
operands. 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. On `fetch` it selects
the remote each selected repository contacts. On `pull` and `push` a ready local clone
family name binds to that workspace instead; on `merge` the name is family-only (`gwz
merge --remote <name> [<ref>]`).
--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.
--verbose
Show one transport diagnostic for every remote authentication attempt. These diagnostics
are omitted from normal human output and remain available in --json and --jsonl output.
--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