// ZVCS — VERB REFERENCE

git zsync reconcile every submodule to its tracked mainline, attached

git zsync [<path>...]

Fetches and fast-forwards every submodule to its tracked mainline (origin/main, else origin/master), leaving HEAD attached to that branch — detached HEAD never happens.

Fast-forward only; a submodule whose worktree is dirty or whose history has diverged is skipped rather than forced. Optional paths limit the operation to the named submodules.

git zbump forward-only submodule gitlink bumps, then commit them

git zbump [<submodule-path>...]

Advances the parent repository's recorded gitlink for each submodule to that submodule's current HEAD, but only when the new commit is a descendant of the recorded one — a forward-only bump that can never regress a pointer.

The coalesced bumps are then committed, clearing git's "(new commits)" status marker. Paths limit the set of submodules considered.

git zdaemon control the singleton machine-wide coordinator

git zdaemon <start|stop|restart|reload|status|info|ping|log>

Controls the one machine-wide daemon (state under ~/.zvcs, socket ~/.zvcs/zvcs.sock) that replaces git's index.lock with a fair per-repo queue and hosts the async job queue, the SQLite ledger, and reactive autonomy.

start/stop bring it up and down; restart and reload respawn it, re-reading config; status and info report liveness and pid/socket/paths/config; ping is a scriptable liveness check; log [-n N] [-f] shows or tails ~/.zvcs/zvcs.log, whose every line opens with a local RFC-3339 stamp (2026-08-20T14:03:11-07:00) ahead of its [zvcs ...] tag.

git zconfig inspect and toggle the daemon's [zvcs] feature switches

git zconfig [<name> [on|off|<count>|default]]

Turns the daemon's autonomy features on and off from the CLI instead of hand-editing ~/.gitconfig. With no argument it lists every setting, its effective value, and whether it is set in your config (marked *) or showing the built-in default.

The boolean switches are autoreconcile (auto-sync submodules to origin/main on change), autobump (forward-only gitlink bumps + commit), autocrawl (crawl zvcs.crawlroots into the index on daemon start), autostatus (recompute a repo's status cache when it changes), autohook (fire each repo's zvcs.hook on change), and autodups (fan a commit out to local duplicate checkouts) — all off by default. Set them with git zconfig <name> on|off.

The numeric knobs are statusinterval (status-cache backstop sweep in seconds, default 10, 0 disables), watchmru (file-watch the N most-recently-used repos, default 512, 0 disables), and interval (autonomy debounce in seconds, default 30). Set them with git zconfig <name> <count>.

git zconfig <name> shows a single setting; git zconfig <name> default reverts it to the built-in default; git zconfig all on|off flips every autonomy switch at once (off also zeroes the two background loops so the daemon idles).

Writes go to the global config (~/.gitconfig), the file the daemon reads. A change reloads a running daemon automatically so it takes effect at once; if no daemon is running the new value applies on its next start (toggling never spawns one).

git zrepos list indexed git repositories

git zrepos [<pattern>...] [--json]

Lists every git repository in the machine-wide index, one path per line (pipe-clean), a drop-in for a shell repo-list.

Patterns filter the output by case-insensitive substring match.

git zreindex (re)crawl for git repositories and refresh the index

git zreindex [--sync|--async] [<path>...]

Crawls for git repositories and records them in the ledger, pruning ones deleted from disk. The walk is parallel and skips mounts that would hang a whole-device scan (kernel pseudo-filesystems, network volumes, the macOS data-volume firmlink).

At a terminal it runs async by default — the crawl detaches and results go to zvcs.log; piped or scripted it runs inline so "indexed N, pruned M" stays on stdout. --sync and --async override the default.

git zjobs list recent async jobs

git zjobs [-n <count>] [--json]

Lists recent jobs from the ledger, newest first. -n limits the count.

git zjob show or control an async job

git zjob <id> | git zjob <stop|restart> <id>

Shows one job's ledger record, or stops (cancels) / restarts (re-enqueues) a running or queued job by id.

git zcommit queue an atomic staged-commit job

git zcommit [<path>...] -m <msg> [--push]

Submits a fire-and-forget staged-commit job to the daemon and returns a job number; --push chains a push after the commit.

Falls back to synchronous execution when no daemon is running.

git zpush queue an async push job with a fast-forward pre-flight

git zpush [<refspec>]

Submits a fire-and-forget push job to the daemon. A network-free / live ls-refs pre-flight refuses a non-fast-forward before the job is enqueued. Falls back to synchronous execution when no daemon is running.

git zsubmit run an arbitrary command as an async daemon job

git zsubmit [--] <command> [args...]

Ships an arbitrary command to the daemon's worker pool as an async job and prints the job id. Track it with git zjobs and git zjob <id> (which shows its state and captured output), and cancel it with git zjob stop <id> — the same ledger and controls as zcommit/zpush.

The command runs in the current directory (a git repository is not required — a repo-less job simply records with no repo) with no shell, so submit sh -c "..." when you need pipes, redirects, or globbing. It runs with the submitter's carried git-identity environment; otherwise it inherits the daemon's. With no daemon running, it executes inline.

git zrepl interactive console over every zvcs command

git zrepl

Opens an interactive line console. Each line is run exactly as git <line> would be, so it drives every dispatchable command — the z* superset verbs and every git-compat porcelain command alike (the latter operating on the current repository), doubling as a live daemon/ledger console.

A line is word-split the way git splits an alias value: single and double quotes group their contents and a backslash escapes the next character, so commit -m "two words" reaches the verb as one argument. Nothing else is expanded — no variables, no globs — and an unclosed quote is reported without ending the session.

On a terminal it opens with a stats banner and full line editing: Tab completes the command word against every verb (superset + porcelain), with command history persisted across sessions. Piped stdin falls back to a raw line reader so scripts and heredocs stay usable. Type exit or quit, or press Ctrl-D, to leave.

git zbanner reprint the zrepl startup banner

git zbanner [--color|--no-color]

Prints the banner git zrepl shows at startup: the zvcs logo, then a box of live stats — os/arch/pid, core count, indexed repository count, and the superset/git-compat/total verb counts.

Every number is read at call time, so re-running it inside a console reflects the tree as it is now (repos indexed since the console opened, a newer build's verb counts) rather than as it was at startup. The repository count comes from the ledger and reads as — when no index exists yet.

Color is on for a terminal unless NO_COLOR is set; --color and --no-color (alias --mono) force it either way, so the ANSI form can be redirected to a file and the plain form kept on a tty.

git zclaim lease a repository for this session

git zclaim [<path>]

Takes an advisory per-repo lease for the current session (ZVCS_SESSION), refusing if another agent already holds it, so concurrent agents do not collide on the same repository.

git zunclaim release a repository lease

git zunclaim [--force] [<path>]

Releases a lease held on a repository. --force releases a lease held by another session.

git zwho list active claims

git zwho [--json]

Lists active claims — which session holds a lease on which repository.

git zstatus working-tree status of indexed repositories

git zstatus [--all] [--json]

Reports the current repository's working-tree status live. --all reads every indexed repository's status from the daemon-maintained cache with no filesystem walk.

git zlog machine-wide reflog timeline across indexed repositories

git zlog [-n <count>]

Merges every indexed repository's reflog into one machine-wide timeline, newest first. -n limits the count.

git zundo rewind a repository one reflog step

git zundo [<path>]

Rewinds a repository one reflog step — a reset --hard to the previous HEAD. Refuses on a dirty worktree.

git zsnapshot record the tree's HEADs as a restore point

git zsnapshot <name>

Records the HEAD of the repository and every nested submodule as one named restore point.

git zrestore reset the whole tree back to a snapshot

git zrestore <name>

Resets the whole tree — the repository and every nested submodule — back to a named snapshot.

Each repository is reset hard to its recorded commit, so tracked changes are discarded and untracked files are left alone. A snapshot records commit ids, not branch names: the branch checked out at restore time is the one moved onto the recorded commit, and whatever it pointed at is reachable afterwards only through its reflog.

A repository that cannot be reset — moved, removed, or missing the recorded commit — is named on stdout and counted in the summary, and the run exits non-zero rather than reporting a half-restored tree as a success.

git zsnapshots list snapshots

git zsnapshots

Lists snapshot names and their repository counts.

git zworktree tree-wide private worktrees

git zworktree <add <name>|list|remove <name>>

add <name> provisions a complete, object-sharing, isolated worktree of the repository plus all nested submodules (each on a zwt/<name> branch) at ~/.zvcs/worktrees/<name>/, so each agent gets a private tree that cannot collide with any other — no re-clone.

list and remove <name> manage them.

remove tears down the worktree tree and, in each repository, the linked-worktree metadata it provisioned — identified by the round trip between the worktree's .git pointer and that metadata's own gitdir file. A pointer that is unreadable, malformed, symlinked, or names anything else is refused by name on stderr and left on disk, and the command exits non-zero rather than deleting a path it cannot prove it wrote.

git zstash stash every dirty repo in the tree as one unit

git zstash [<name>]

Parks uncommitted work across every dirty repository in the tree as one named unit.

git zunstash pop the tree-wide stash back

git zunstash [<name>]

Restores (pops) a tree-wide stash, last-in-first-out, applying onto the same commits it was stashed on. A repository whose HEAD has since moved is reported and its stash kept intact.

git zstashes list tree-wide stashes

git zstashes

Lists tree-wide stashes and their repository counts.

git zup reconcile the tree at cwd to latest origin/main

git zup [<path>]

Brings the whole tree — the top-level repository and every nested submodule — to latest origin/main (fetch, then fast-forward, staying attached). A dirty or diverged repository is skipped.

git zforeach run a command across all or a subset of indexed repos

git zforeach [<selectors>] -- <command>...

Runs a command across all indexed repositories, or a subset, in parallel.

Selectors: a bare <pattern> (substring), --repo <p>, --dirty, --ahead, --behind, --claimed, and --session <s>. Everything after -- is the command to run in each selected repository. See git help zselectors for the full selector grammar.

git zselectors the shared selector grammar the parallel verbs accept

git zselectors

Many superset verbs take an optional leading [selectors] argument that narrows which indexed repositories they act on — zforeach, zheads, zdirty, zpull, zgrep, zfetch, zgc, zcommitall, and the rest. This page documents that shared grammar; git zselectors prints a short version to the terminal.

With no selector a verb acts on EVERY indexed repository. The selectors are: a bare <pattern>, a case-insensitive substring matched against each repo's working-tree path (repeatable — all patterns must match); --repo <pattern>, the same thing spelled out; --dirty, repos with uncommitted tracked changes; --ahead and --behind, repos ahead of or behind their upstream; --claimed, repos with an active lease (git zclaim); and --session <s>, repos leased by session <s>.

Selectors COMPOSE with AND — a repo must match every selector given (so --ahead --behind is empty, since a repo is never both). --dirty, --ahead, and --behind read the daemon's status cache (kept warm by the status maintainer), so they reflect the last scan rather than a live check.

Examples: git zheads (all repos) vs git zheads cask (only repos whose path contains "cask"); git zforeach --dirty -- git status runs git status in every dirty repo; git zpull --behind fast-forwards only the repos behind their upstream; git zgrep --repo web TODO searches "TODO" in repos matching "web".

git zhook manage the current repo's ref-change hook

git zhook <set <command>|unset|show|list|test>

Manages and tests the current repository's ref-change hook (zvcs.hook), which the daemon runs on every ref-change when zvcs.autohook is enabled. set installs a command, unset removes it, show/list display it, and test runs it once.

git ztrigger arm any directory to run a command on every ref-change

git ztrigger <DIR> <command>... | git ztrigger <list|rm DIR|test DIR>

The directory-addressed front-end to the hook system: unlike zhook (current repo only) it takes an explicit path, so any repository on the machine can be wired without cd-ing into it, and it flips the master switches itself — no raw git config needed.

git ztrigger DIR CMD writes DIR's local zvcs.hook, indexes DIR, turns on the global zvcs.autohook switch, and reloads the daemon, so CMD runs on every ref-change in DIR. list, rm DIR, and test DIR manage armed triggers.

git zwatch watch a directory's status without running a command

git zwatch <DIR> | git zwatch <list|rm DIR>

The command-less form of ztrigger: it indexes DIR and turns on zvcs.autostatus so the daemon maintains DIR's cached status on every ref-change, without running any command. list and rm DIR manage watches.

git zshadow install the ~/.zvcs shadow and print the shell lines for it

git zshadow [<dir>] [-n|--print] [--all]

Sets up the whole shadow install in one command: a git symlink to this binary in <dir> (default ~/.zvcs/bin), a git-<verb> dashed link beside it for every verb the dispatcher serves, every superset man page under ~/.zvcs/man, the HTML documentation set under ~/.zvcs/share/doc/git-doc (what git help -w <cmd> opens for every page git's own installed HTML manual does not hold), and the zvcs-forked zsh completion as ~/.zvcs/completions/_git. Everything installed is compiled into the binary, so nothing is needed from the source tree.

stdout carries shell code only — the export PATH line for the bin directory, the export MANPATH line for the man directory, and the fpath line for the completion directory — so eval "$(git zshadow)" sets the current shell up and the same lines paste into ~/.zshrc. The install summary goes to stderr, where an eval leaves it alone.

A PATH or MANPATH line the environment already satisfies is printed commented out, so re-evaluating never duplicates an entry and the line is still visible to uncomment when pasting into an rc file; --all prints every line uncommented. fpath is a zsh variable rather than an exported one, so it cannot be inspected from here and its line is always live — put it before compinit, and typeset -U fpath keeps repeats harmless.

-n (--print) prints the lines without installing anything. Paths under $HOME are written as $HOME/... so the lines are portable across machines.

Homebrew installs this binary as zvcs rather than git, so the bootstrap there is zvcs zshadow — the same command under its other name. Once the printed PATH line is in effect, git is this binary and git zshadow is the way to re-run it, which a brew upgrade calls for: the shim points at the binary that installed it.

Idempotent: a correct symlink is left alone, a stale one is repointed, a real file of the same name is never clobbered, and the completion is rewritten only when its content differs.

git zdashed install git-<verb> symlinks and man pages

git zdashed [<dir>]

Installs a git-<verb> symlink for every builtin and superset verb into <dir> (default ~/.zvcs/bin), so the dashed external forms resolve to this binary once stock git is removed.

It also writes every extension man page under ~/.zvcs/man, so man git-<verb> resolves when that directory is on MANPATH, and the HTML documentation set under ~/.zvcs/share/doc/git-doc, so git help -w <cmd> finds a page for every command without generating one first, on a host whose git installation ships no HTML manual of its own.

git zverbs list every zvcs extension verb and its usage

git zverbs [--json]

Lists every zvcs extension (z*) verb with its one-line usage, sourced from each verb's own -h so the listing can never drift.

git zcd change the working directory (for the zrepl console)

git zcd [<dir>|-]

Changes the process working directory: no argument goes to $HOME, - goes to the previous directory ($OLDPWD), and a leading ~ expands to $HOME. OLDPWD and PWD are updated so zcd - round-trips, exactly as a shell's cd does.

The zrepl console runs each line in one long-lived process, so a zcd persists across lines — it is what makes the console navigable like a shell. Run standalone it only moves this process's cwd (it cannot change the parent shell's), so it is aimed at the console.

git zpwd print the working directory

git zpwd

Prints the current working directory. Paired with zcd for shell-like navigation inside the zrepl console.

git zls git-aware directory listing

git zls [-alrt] [<path>]

Lists a directory with a two-column git status field per entry, like eza --git: the first column is the staged status (index vs HEAD), the second the unstaged status (worktree vs index). Letters follow eza: N new, M modified, D deleted, R renamed, C copied, T type-change, U conflicted, I ignored, and - unchanged. A directory folds the status of the paths under it, so a subtree with any change is flagged. Outside a git repository the column is omitted.

Flags: -a includes dotfiles, -l is a long listing (permissions, size, relative mtime), -t sorts by modification time (newest first), and -r reverses. The per-path status is the same walk git status performs.

On a terminal the output is colored from the same palette eza uses: LS_COLORS for file kinds and *.ext extensions, then EXA_COLORS/EZA_COLORS for the permission bits, size, date, git columns, and punctuation — so it matches the user's eza. NO_COLOR disables color.

git zenv print, set, or query environment variables

git zenv [<NAME=VALUE>...|<NAME>...]

With no arguments, prints every environment variable as NAME=VALUE, sorted. A NAME=VALUE argument sets that variable; a bare NAME prints its value (nothing if unset).

In the zrepl console a variable set with zenv persists for every later git line — set GIT_AUTHOR_NAME, ZVCS_SESSION, and the like once and the whole session sees it.

git zunset remove environment variables

git zunset <NAME>...

Removes one or more environment variables from the process, the complement of zenv NAME=VALUE. In the zrepl console the change persists for later git lines.

git zecho print arguments joined by a space

git zecho [-n] [<arg>...]

Prints its arguments joined by a single space. A leading -n suppresses the trailing newline. Arguments are printed literally — there is no shell variable or glob expansion.

git zdoctor health check of the zvcs environment

git zdoctor

Runs a set of environment checks and prints each as OK, WARN, or FAIL: whether this binary is the git on PATH, whether $ZVCS_HOME exists and can be written, whether the coordinator daemon is running, whether the ledger opens and answers a query, how many man pages are installed, whether ~/.zvcs/man is on MANPATH, and whether the dashed git-<verb> symlinks are installed.

The two states that stop zvcs working are FAIL: a home that exists but cannot be written, and a ledger that exists but cannot be read — a corrupt or unreadable store leaves the file in place while every verb that reads it exits non-zero, so a check that only looked for the path reported OK straight through it. Everything else is advisory and reports WARN, which keeps a non-zero exit meaningful.

The process exits non-zero only when a hard FAIL is found, so it is usable in scripts and CI.

git zmkdir create directories

git zmkdir [-p] <dir>...

Creates each named directory. -p creates any missing parent directories and does not error if the directory already exists. A native filesystem convenience for the zrepl console.

git ztouch create files or update their mtime

git ztouch <file>...

Creates each named file if it does not exist (leaving existing contents intact) and updates its modification time to now, like the shell's touch.

git zrm remove files and directories

git zrm [-r] [-f] <path>...

Removes files from the filesystem — this is not git rm (which stages a removal in the index); it deletes on disk. -r removes directories recursively, -f ignores paths that do not exist. Symlinks are removed, never followed.

git zcp copy files and directories

git zcp [-r] <src>... <dst>

Copies files; -r copies directories recursively. With several sources, <dst> must be an existing directory and each source is copied into it under its own name; with one source and a non-directory <dst>, <dst> is the copy's name.

git zmv move or rename files and directories

git zmv <src>... <dst>

Moves or renames paths. With several sources, <dst> must be an existing directory. A rename is used when possible, falling back to copy-then-remove when the move crosses filesystems. This is not git mv (which also updates the index); it only moves on disk.

git zcat print file contents

git zcat <file>...

Writes each named file's bytes to stdout, in order, like the shell's cat.

git zln create a hard link or symlink

git zln [-s] <target> <link>

Creates <link> pointing at <target>: a hard link by default, or a symbolic link with -s.

git zheads HEAD of every indexed repo, in parallel

git zheads [selectors] [--json]

Prints each indexed repository's checked-out branch (or (detached)/(unborn)), short HEAD id, and a * when the worktree has tracked changes — a one-glance view of where every repo in the machine sits.

Selectors are the same as zforeach: bare <pattern>, --repo <p>, --dirty, --ahead, --behind, --claimed, --session <s>. The probe is a native gix read run across all repos on a bounded worker pool.

git zdirty list indexed repos with tracked changes

git zdirty [selectors] [--json]

Lists only the indexed repositories whose worktree has uncommitted tracked changes (the same "dirty" gix reports for zstatus; an untracked-only repo counts as clean). Scanned in parallel. Selectors narrow the set as in zforeach.

git zbranches local branches of every indexed repo

git zbranches [selectors] [--json]

Prints each indexed repository's local branch names, grouped by repo, scanned in parallel.

git ztags tag count of every indexed repo

git ztags [selectors] [--json]

Prints how many tags each indexed repository has, scanned in parallel.

git zremotes remotes and URLs of every indexed repo

git zremotes [selectors] [--json]

Prints each indexed repository's remotes and their fetch URLs, grouped by repo, scanned in parallel.

git zsize on-disk .git size of every indexed repo

git zsize [selectors] [--json]

Prints each indexed repository's on-disk .git size, largest first, with a total, so the heaviest repos in the tree are obvious. Sizes are summed with a native filesystem walk in parallel.

git zage HEAD commit age of every indexed repo

git zage [selectors] [--json]

Prints how long ago each indexed repository's HEAD commit was made (a relative time like 3 days ago), scanned in parallel — a quick read of which repos are stale.

git zpull parallel fetch + fast-forward of every indexed repo

git zpull [selectors]

Fetches and fast-forwards every selected indexed repository to its tracked mainline, in parallel, using the same native ff-only reconcile as zsync: a dirty or diverged repo is reported and skipped, never forced.

Where zsync/zup act on the current submodule tree, zpull acts on the machine-wide index, so selectors (--repo, --behind, …) scope which repos are pulled.

git zattach re-attach every detached-HEAD indexed repo to its mainline

git zattach [selectors]

Re-attaches every selected indexed repository that is on a detached HEAD to its mainline branch (main, else master), fleet-wide — the kill-switch for the detached HEADs git submodule update leaves behind across the whole index.

It uses the same local, no-clobber attach zsync applies to submodules: it never contacts a remote, never moves the checked-out commit, and never touches the worktree or index — it only creates or fast-forwards the local mainline branch to the commit HEAD is already at and makes HEAD symbolic to it, so it is safe even on a dirty repo. A repo whose local mainline is ahead of or diverged from HEAD is refused rather than clobbered (catching the worktree up is zpull/zsync's clean-only job); a repo with no main or master anywhere is skipped. It reports how many were attached, already on a branch, had no mainline, or were refused.

git zgrep parallel content search across indexed repos

git zgrep [selectors] [-i] <pattern> [--json]

Searches the tracked file content of every indexed repository for <pattern> (a regular expression) in parallel, printing path:line:text for each match. -i is case-insensitive; binary files are skipped, as git grep does.

Only tracked, non-conflicted worktree files are searched. Selectors narrow the repo set as in zforeach.

git zahead indexed repos ahead of their upstream

git zahead [selectors] [--json]

Lists the indexed repositories that have commits not yet on their configured upstream, with the count, computed in parallel. Repos with no upstream are omitted.

git zbehind indexed repos behind their upstream

git zbehind [selectors] [--json]

Lists the indexed repositories whose upstream has commits they lack, with the count, computed in parallel. Repos with no upstream are omitted.

git zunpushed per-repo unpushed commits (the detailed zahead)

git zunpushed [selectors] [--json]

Lists, per indexed repository, the actual commits HEAD has that its upstream lacks — short id and summary line, grouped under the repo path — computed in parallel. Where zahead gives only a count, this shows what is unpushed. The list is capped per repo so a long divergence cannot flood the output; repos with no upstream or nothing unpushed are omitted.

git zunpulled per-repo commits the upstream has that local lacks

git zunpulled [selectors] [--json]

Lists, per indexed repository, the commits on the configured upstream that the local branch lacks — short id and summary, grouped per repo. The detailed form of zbehind. A git zfetch first makes the upstream refs current. Repos with no upstream or nothing unpulled are omitted.

git zauthors commit counts by author across indexed repos

git zauthors [selectors] [--json]

Walks every indexed repository's HEAD history in parallel, tallies commits by author Name <email>, aggregates across all repos, and prints them ranked by count — a machine-wide contribution summary.

git zhot indexed repos ranked by recent activity

git zhot [selectors] [<days>] [--json]

Ranks indexed repositories by the number of commits made in the last <days> (default 30), most active first, counted in parallel — a quick read of where work is happening across the tree.

git zconflicts indexed repos mid-operation or conflicted

git zconflicts [selectors] [--json]

Lists the indexed repositories that are in the middle of a merge, rebase, cherry-pick, revert, or bisect, or that have unmerged (conflicted) index entries, with the operation(s) named — so a stuck repo among many is found at a glance.

git zfetch parallel git fetch across indexed repos

git zfetch [selectors]

Runs git fetch in every selected indexed repository concurrently, through this binary's own porcelain and fair per-repo lane. Output is grouped per repo and failures are recorded in the ledger.

git zgc parallel git gc across indexed repos

git zgc [selectors]

Runs git gc in every selected indexed repository concurrently — machine-wide maintenance in one command.

git zfsck parallel git fsck across indexed repos

git zfsck [selectors]

Runs git fsck in every selected indexed repository concurrently, to check object integrity across the whole tree at once.

git zprune parallel git prune across indexed repos

git zprune [selectors]

Runs git prune in every selected indexed repository concurrently, removing unreachable objects tree-wide.

git zreset parallel git reset across indexed repos

git zreset [selectors] [--soft|--mixed|--hard] [<ref>]

Runs git reset in every selected indexed repository concurrently. The mode flag and optional <ref> pass straight through to git, so the default (as git's) is --mixed HEAD, which unstages. --hard discards worktree changes across the whole selection — narrow it with selectors (e.g. --dirty) first.

git zabort abort an in-progress operation across mid-op repos

git zabort [selectors]

Aborts an in-progress merge, rebase, cherry-pick, or revert in every selected indexed repository that is mid-operation — running the matching --abort — and skips repos with nothing in progress. Cleans up after a fan-out (or a many-agent session) that left repos stuck in a half-finished operation.

git zcheckout check out a branch in every repo that has it

git zcheckout [selectors] <branch>

Checks out <branch> in every selected indexed repository that already has it, in parallel. A repo without the branch is skipped — the branch is never created — so this is a safe way to move a whole tree onto a shared branch name.

git ztagall create a tag at HEAD in every indexed repo

git ztagall [selectors] <tag>

Creates tag <tag> at HEAD in every selected indexed repository, in parallel. A repo that already has the tag reports the failure rather than moving it.

git zcommitall commit tracked changes across every dirty repo

git zcommitall [selectors] -m <msg>

Commits tracked changes (git commit -a) with message <msg> in every selected indexed repository whose worktree is dirty, in parallel. Clean repos are skipped. Untracked files are not staged (as with commit -a).

git zpushall push every indexed repo that is ahead

git zpushall [selectors]

Runs git push in every selected indexed repository that is ahead of its upstream, in parallel. Repos that are not ahead (or have no upstream) are skipped, so no needless network calls are made.

git zclean remove untracked files across indexed repos

git zclean -f [selectors]

Runs git clean -fd — remove untracked files and directories — in every selected indexed repository, in parallel. Because it deletes, the -f flag is required; ignored files are left (as git clean does without -x).

git zwait block until a repo's async jobs drain

git zwait [<path>]

Blocks until the repository at <path> (or the current directory) has no queued or running async jobs (zcommit/zpush) left in the ledger — the join for that repo's fire-and-forget work. With no daemon there are no jobs, so it returns at once.

git zqueue list queued and running async jobs

git zqueue

Lists the async jobs currently queued or running in the ledger (id, state, kind, repo) — what the daemon is working through right now.

git zbarrier block until the async queue is idle

git zbarrier

Blocks until the entire async job queue is idle — every repository's queued and running jobs have drained — the global join after a burst of zcommit/zpush.

git zstale indexed repos not committed to in a while

git zstale [selectors] [<days>] [--json]

Lists the indexed repositories whose HEAD commit is older than <days> (default 90), with how long ago — surfacing abandoned repos across the tree. Scanned in parallel.

git zlast indexed repos by most recent commit

git zlast [selectors] [--json]

Lists indexed repositories ordered by HEAD commit time, most recently committed first, each with its relative age — where work happened most recently.

git zbig largest tracked files across indexed repos

git zbig [selectors] [<n>] [--json]

Lists the largest tracked files across every indexed repository, top <n> (default 20), by on-disk size — bloat hunting tree-wide. Files are gathered in parallel.

git zfiles tracked file count per indexed repo

git zfiles [selectors] [--json]

Prints the number of tracked files in each indexed repository, largest first, scanned in parallel.

git zcommits HEAD-history commit count per indexed repo

git zcommits [selectors] [--json]

Counts the commits reachable from HEAD in each indexed repository — its history depth — and prints them deepest first, walked in parallel.

git zpristine indexed repos that are clean and in sync

git zpristine [selectors] [--json]

Lists the indexed repositories that need nothing: no uncommitted changes, on a branch (not detached), and in sync with their upstream (or having none configured). The complement of zdirty/zahead/zbehind/zconflicts — the green set — computed in parallel.

git zdivergent indexed repos diverged from upstream

git zdivergent [selectors] [--json]

Lists indexed repositories that are both ahead of and behind their upstream — history has forked, so a merge or rebase is needed. Computed in parallel.

git zorphans indexed repos with no remote

git zorphans [selectors] [--json]

Lists indexed repositories with no remote configured — nothing to fetch from or push to. Scanned in parallel.

git zsessions active sessions ranked by repos held

git zsessions [--json]

Lists the sessions that currently hold claims, ranked by how many repositories each holds — which agent is working the most of the tree.

git zidle indexed repos with no active claim

git zidle [selectors]

Lists indexed repositories that no session has claimed — the ones free for an agent to pick up. Selectors narrow the candidate set as in zforeach.

git zdashboard live tiled TUI: fleet, events, and commands on one screen

git zdashboard [--once] [--json]

A live, tiled dashboard of the whole indexed tree on one screen: a header of aggregate totals (dirty, ahead, behind, diverged, detached, clean, claims, sessions, queue, and whether the daemon is up) over four tiles — a FLEET table (every repo, most recently active first, with the on-screen rows' HEAD state live-refreshed so nothing is stale), a PROCESSES tile (each committing ppid with its command, cwd, commit tally, live/dead state and last-commit age, as zppid shows — live processes first, then most commits), an EVENTS feed (commits, reconciles, status changes, as zevents shows), and a COMMANDS feed (every git command run across the machine, with the agent that ran it, as zcommands shows). Press q or Esc to quit.

Every tile reads the daemon-maintained status cache and ledger, not a live per-repo walk, so the dashboard stays responsive across thousands of repos. The COMMANDS tile is populated once command logging is on (git zcommands enables it).

For scripting, --once or --json (or a non-terminal stdout) prints the instant text summary instead of the TUI — the same aggregate counts, one screen, no interaction.

git ztop live htop-style fleet monitor, most churn on top

git ztop [selectors] [--interval <secs>] [--once] [--mono]

A full-screen, live monitor of the whole indexed tree — an htop for the fleet. A header shows the totals (dirty, ahead, behind, diverged, detached, clean, claims, sessions, queue depth, and whether the daemon is up); a table lists every repo with a churn bar, path, HEAD, state, and how long ago it last changed.

Repos are sorted with the most churn on top: when a repo's HEAD or dirty flag changes between frames (the daemon rewrote its status row), its churn score bumps and then decays, so whatever is moving right now rises to the top, like an htop CPU column. Press s to cycle the sort (churn / state / name), the arrows / PgUp / PgDn / g / G to scroll, and q (or Esc) to quit.

Each frame reads the daemon-maintained status cache, not a live per-repo scan, so it stays responsive across thousands of repos — start the daemon (git zdaemon start) so the cache stays warm and churn reflects real activity. Selectors narrow the view to a subset; --interval sets the refresh seconds, --mono (or NO_COLOR) drops color, and --once (or a non-terminal stdout) prints a single plain-text frame for scripts.

git zevents one live feed of commits/reconciles/status-changes across the tree

git zevents [-n <count>] [--kind commit|stage|status|reconcile] [--repo <substr>] [--json] [--no-follow]

Prints a single structured, live feed of what is happening across the whole indexed tree: commits (a HEAD moved), status-changes (a dirty or sync transition), and reconciles (a fetch-free fast-forward the daemon applied). It shows a short backlog, then follows live.

Events come from the index's append-only events table, written by triggers on the status cache that both the whole-tree poller (statusd) and the instant file-watcher (watch) maintain, so activity anywhere is captured with no per-call plumbing. -n sets the backlog size, --no-follow prints the backlog and exits, --kind filters to one event kind, --repo filters by path substring, and --json emits NDJSON (one event per line) for tooling.

git ztail alias of git zevents

git ztail [-n <count>] [--kind commit|stage|status|reconcile] [--repo <substr>] [--json] [--no-follow]

An alias for git zevents — the single live feed of commits, reconciles, and status-changes across the whole indexed tree. See git help zevents for the full description.

git znative the plugin package manager: install and load native and script plugins

git znative load|add|remove|list|info|update|gc|clean [SOURCE|NAME]

Installs plugins that extend this binary with new subcommands, from one content-addressed global store under $ZVCS_HOME/pkg. Two kinds are served from that one store: a *native* plugin is a Rust cdylib compiled against the znative C ABI and loaded with dlopen, and a *script* plugin is a repository of git-<verb> executables. Ported from the zshrs package manager of the same name.

A source is owner/repo, github:owner/repo, git+URL, or a local path:DIR; any remote form may carry an @ref suffix to pin a tag, branch or commit (owner/repo@v1.2.0), and the pin is recorded so update re-fetches that exact ref. add resolves the source, builds the cdylib when the plugin ships source, copies the loadable subset into store/<name>@<version>/, SHA-256 pins it, and records what it provides in installed.toml. load is the idempotent form for a bootstrap script: it installs a source that is not in the store yet and otherwise just re-verifies, with no network.

A native plugin's verbs are discovered by loading it at install time, never declared: whatever it registers through the ABI is what gets recorded. A plugin may also *override* an existing verb, in which case its handler runs in place of the built-in one and calls back through the host to run the original. git znative itself can never be overridden, so a bad plugin cannot lock you out of removing it.

Nothing is loaded until a verb proves to belong to a plugin. The index's two derived tables, verbs.tsv and overrides.tsv, answer that question, and are deleted rather than written empty when there is nothing in them — so a machine with no plugin installed pays two failed stats per command and never opens a file. list, info and remove manage what is installed; gc reclaims store directories left by old versions plus the clone cache, and clean clears the scratch directories.

git zintercept AOP hooks that run advice around matching git commands

git zintercept before|after|around <pattern> -- <cmd> | list | remove <id> | clear

Registers aspect-oriented advice that fires around git commands, ported from zshrs. A before hook runs a shell command before a matching git command; an after hook runs after it (with the command's exit status and timing available); an around hook replaces it, and runs the original itself when it chooses. <pattern> matches the git subcommand — commit, push, a glob like commit *, or * / all for everything.

The advice <cmd> is a shell command run via sh -c. It sees the intercepted command through the environment: INTERCEPT_NAME (the subcommand), INTERCEPT_ARGS, and INTERCEPT_CMD (the full git ... line); after-advice also gets INTERCEPT_STATUS, INTERCEPT_MS, and INTERCEPT_US. An around advice runs eval "$INTERCEPT_CMD" to proceed with the original (that child is not re-intercepted) — the eval is required, because INTERCEPT_CMD is a whole command line and the quoted-without-eval form makes the shell look for a single program by that name.

Registrations persist to $ZVCS_HOME/intercepts.tsv and load at dispatch; when none are registered the cost on every git command is a single stat. list shows all with their ids, remove <id> deletes one, and clear removes them all.

git zcommands live feed of every git command run across the fleet

git zcommands [-n <count>] [--repo <substr>] [--json] [--no-follow] [--off] [--clear]

Streams every git command run anywhere on the machine, in real time. Because the zvcs git binary shadows real git on PATH, every invocation flows through one dispatcher; when logging is on, each records a line — time, pid, working directory, and the command — to its own log at $ZVCS_HOME/commands.log (separate from the daemon log). This verb prints a backlog and then follows the log live, so commands from every repo and every concurrent shell scroll past as they run.

Running it turns logging on (a marker file, so the cost on every other git command is a single stat when it is off) and notes where the log lives. -n sets the backlog size, --no-follow prints the backlog and exits, --repo filters to commands whose directory contains a substring, and --json emits NDJSON for tooling. --off stops logging; --clear truncates the log. The live viewers (zcommands, zevents, ztail, ztop) are excluded so watching does not feed itself.

git zaudit queryable audit trail over the fleet command log

git zaudit [--agent <ppid>] [--repo <substr>] [--cmd <substr>] [--mutating] [--summary] [-n <count>] [--json]

The historical, accountable side of the same command log zcommands feeds — $ZVCS_HOME/commands.log. Where zcommands follows the live stream, zaudit queries the record: it answers "which agent ran which command against which repo, and when" across a fleet of concurrent agents. Each logged line carries the time, the command's pid, its parent pid (the agent that launched it), the working directory, and the git argv.

Filters compose: --agent <ppid> restricts to one agent, --repo <substr> to repos whose directory contains a substring, --cmd <substr> to commands whose argv contains a substring, and --mutating to state-changing subcommands only (commit, push, reset, rebase, merge, checkout, and the mutating z-verbs). -n limits how many matching records print (newest last); --json emits NDJSON.

--summary replaces the record list with tallies: how many commands each agent ran, and how many of each subcommand, ranked by count — an at-a-glance accountability view of who did what across the tree.

git zscan parallel secret scan of tracked content across the fleet

git zscan [selectors]

Scans the tracked file content of every selected indexed repo, in parallel over the shared worker pool, for common credential patterns — AWS access keys, PEM private keys, GitHub/Slack/Google tokens, JWTs, and high-entropy key = "..." assignments — using the same native, fork-free content walk zgrep does. Each hit prints as path:line:pattern:snippet.

Binary files are skipped, output is capped per repo so one flooded tree cannot drown the rest, and the whole run exits non-zero when anything is found — so git zscan drops straight into a pre-push hook or CI gate. [selectors] narrows the set the same way every fleet verb does.

git zsigs fleet commit-signature check (verify-sigs)

git zsigs [selectors] [-n <count>]

Checks commit signatures across the fleet and flags any that are not a good signature — unsigned (N), bad (B), or unverifiable (E/X/Y/R). By default it checks each selected repo's HEAD; -n walks the top N first-parent commits. Each offender prints as <code> <repo> <sha> <subject> (git's %G? codes), and the run exits non-zero if any are found — so it gates a push or CI under an all-commits-must-be-signed policy.

Verification is native where it can be and delegated where it must be: the signature and its signed payload are reconstructed from the commit object in-process (the gpgsig header removed and de-folded exactly as git does), then handed to gpg — the same tool git shells to; there is no in-process crypto in git either. A commit with no signature is N without running anything; a present signature that gpg cannot check (no public key, gpg absent) is E, never a fabricated good. SSH-format signatures report E in this pass (verifying them needs an allowed-signers file). The same machinery backs the %G? and %GK pretty-format placeholders in git log.

git zreview aggregate the pending uncommitted change across the fleet

git zreview [selectors]

The read-side companion to zcommitall: for every selected repo with uncommitted work, it prints the repo's git status --short block grouped under its path, plus the summary line of its diffstat against HEAD, so you can review everything about to be committed across a whole tree of submodules on one screen.

Clean repos are omitted; a trailing line reports how many repos have pending change and how many total entries. The status probe runs through this binary over the shared worker pool, so it is fleet-parallel and reads consistently with every other z-verb.

git zremote fleet-wide remote-URL rewrite

git zremote set <old> <new> [selectors] [-n|--dry-run]

Rewrites remote URLs across the fleet in one command: in every selected repo, any remote whose URL contains the substring <old> is rewritten with <old> replaced by <new>. This is the one-shot answer to moving an org, changing a host, or switching ssh↔https across a tree of submodules.

Each change prints as set <repo>::<remote> <from> → <to>; -n / --dry-run previews every change as would set without touching anything. Writes go through this binary's own remote set-url porcelain over the shared worker pool; the run exits non-zero if any set-url fails.

git zrollback fleet-wide undo of the last mutating operation

git zrollback [selectors] [--steps <n>] [--apply] [--force]

The multi-repo evolution of zundo: across every selected repo it resolves HEAD@{n} from the reflog (n = --steps, default 1) and rewinds to it with reset --hard, undoing the last commit / merge / rebase / reset. The reset is itself reflogged, so a rollback is undoable.

It is **dry-run by default** — with no --apply it prints what each repo *would* do (<current> → <target>) and changes nothing. --apply executes the rollback on the repos that pass the guards.

The guards refuse to lose work: a repo is skipped, not rolled back, when its worktree is dirty, when it is mid-operation (merge/rebase/cherry-pick/revert), or when rolling back would diverge from its remote — the discarded commits are already pushed (sync is up-to-date, behind, or diverged). Rollback is allowed by default only when the commits are local-only (ahead or no-upstream). --force overrides every guard.

git zsched daemon-hosted scheduled fleet commands (a built-in cron)

git zsched add <duration> -- <cmd> | list | rm <id> | clear | run <id>

Schedules a command to run on an interval, hosted by the daemon — a built-in cron for the whole tree. git zsched add 5m -- git zpull --dirty fast-forwards every dirty repo every five minutes; durations are 30s / 5m / 1h / 1h30m style. list shows every schedule with its id and interval, rm <id> removes one, clear removes them all, and run <id> fires one now (synchronously) for testing.

Schedules persist to $ZVCS_HOME/schedule.tsv as id\tinterval\tcommand. The CLI owns every write to that file; the daemon's scheduler thread only reads it (re-reading each tick, so add/rm take effect within one tick with no reload) and tracks each schedule's last-fire time in memory — so the CLI and daemon never contend on the file. A schedule fires one full interval after the daemon first sees it, not on daemon start.

git zpin freeze a repo from daemon autonomy

git zpin [<path>...|list] [--json]

Pins one or more repositories so the daemon's autonomy leaves their pointer alone — a pinned repo is skipped by autobump and reconcile, so its gitlink and HEAD will not move on their own until it is unpinned. Detached-HEAD attach still runs, because re-attaching a detached HEAD heals it without moving the pointer.

With no path it pins the repository at the current directory; with paths it pins each named repository; git zpin list prints every pinned repo. The flag lives in the shared index (repos.pinned), so it survives daemon restarts and is visible to every session. Unfreeze with git zunpin.

git zunpin unfreeze repos pinned from autonomy

git zunpin [<path>...|--all]

Clears the pin set by git zpin, so the daemon resumes autobump and reconcile for the repository. With no path it unpins the repo at the current directory; with paths it unpins each named one; --all unpins every pinned repository at once.

git zbroadcast post and read inter-agent messages

git zbroadcast [--to <session>] [<msg>...]

Sends a message to the other agent sessions working the tree, over the shared index. With a message it broadcasts to every session, or to one with --to <session>; with no arguments it prints this session's unread messages and marks them read.

Read state is tracked per session, so a broadcast is delivered once to each recipient and a sender never sees its own message. It is a pull inbox — messages are read when you run the verb, adding no cost to any other command. Session identity comes from ZVCS_SESSION.

git zhandoff hand a repo's claim to another agent session

git zhandoff <repo-path> <session>

Reassigns the advisory claim (lease) on a repository from the current holder to another session, and drops that session a message noting the handoff. Fails if the repository is not currently claimed.

Claims are the session-attributed "I'm working this repo" signal set by git zclaim; zhandoff transfers one without the receiver having to race for it, so work can be passed cleanly between agents.

git zon run a command on a semantic feed event

git zon [--kind commit|stage|status|reconcile] [--repo <substr>] -- <cmd> | git zon list | git zon rm <id>

Registers a rule that runs a command when a matching event fires on the live feed. Where git ztrigger reacts to raw filesystem events under a directory, zon reacts to typed events — commit, stage, status, reconcile — from the same feed git zevents shows, optionally filtered to repos whose path contains a substring.

The command after -- runs via the shell with ZVCS_EVENT, ZVCS_REPO, ZVCS_DETAIL, and ZVCS_SHA set for the triggering event. git zon list shows every subscription; git zon rm <id> removes one. The daemon watches the feed and runs the matches. Caveat (shared with ztrigger): a command that itself commits or stages can match its own subscription and re-fire — scope it with --kind/--repo.

git zsince what happened across the tree since a time

git zsince <duration|snapshot> [--kind K] [--repo R] [--json]

Prints every feed event — commits, stages, status changes, reconciles — recorded across the whole indexed tree since a point in time. A duration (90s, 45m, 2d, 1h30m, or a bare number of seconds) counts back from now; any other token is treated as a snapshot name and its creation time is the baseline.

This is the scoped "what did the fleet do since X" delta that git zlog's full timeline does not give. --kind and --repo narrow the result to one event kind or to repos matching a substring.

git zcontend live agent-vs-agent contention across the tree

git zcontend [--json]

Shows who is stepping on whom: the session-attributed claims (advisory leases), the per-repo job backlog (how many jobs are queued or running behind each repository in the daemon's fair queue), and the intersection — repositories that are both claimed and have jobs stacked up, i.e. actively contested.

All three are read from the shared index; nothing is mutated. It is the multi-agent observability view git has no notion of, because git only ever sees one repository and one process.

git zwaitfor block until a tree-wide state holds

git zwaitfor <clean|idle|synced|<repo> <sha>> [--timeout <secs>]

Blocks until a condition over the whole tree becomes true, then exits 0 (or 1 on timeout) — a cross-repo barrier on state, where git zbarrier and git zwait are job-scoped. clean waits until every indexed repo is clean; idle until no daemon jobs are queued or running; synced until every repo is up-to-date with its upstream; <substr> <sha> until the repo whose path contains the substring is at the given commit (prefix).

Conditions are read from the daemon's cached status, so the daemon must be maintaining status for the wait to observe changes. An indexed repository that has not been reported on yet is not counted as meeting the condition — a tree nothing is reporting waits and then times out, rather than passing on an empty cache. --timeout bounds the wait (default 60 seconds).

git zgraph fleet topology of duplicate checkouts

git zgraph [--json]

Maps the cross-repository relationship git has no notion of: which local checkouts are the same upstream repository — a dup group, the same origin URL with more than one working tree on the machine. git can never show this, because git only ever sees one repository.

Reads every indexed repository's origin (on demand, so the per-repo config read is acceptable) and lists each dup group with its checkouts, then a summary of repos, distinct origins, dup groups, and repos with no origin.

git zrewind restore the whole tree to a wall-clock time

git zrewind <duration> [--dry-run]

Rewinds the tree — the repository at the current directory and every nested submodule — to the state it was in a given duration ago (2h, 30m, 1d). For each repository it finds the HEAD the reflog shows it had at that time and resets hard to it, reusing the faithful porcelain reset (itself reflogged, so the rewind is undoable). Where git zsnapshot is a manual named restore point, this is any timestamp with no prior setup.

A repository holding uncommitted work of its own is refused so that work is never clobbered. A submodule pointer moved by a child is not such work — a superproject reads as modified the moment a submodule moves, which is the very state a tree-wide rewind undoes — so it does not stop the parent from being rewound; the child is rewound in the same pass. A repository whose reflog does not reach that far back is reported and skipped (the reflog's default 90-day expiry bounds how far back it can go). --dry-run shows exactly what would move without changing anything.

git zguard declarative fleet-wide command policy (refuse or warn)

git zguard deny|warn <pattern> [--when <predicate>] [-m <msg>] | list | rm <id> | clear | test <cmd>...

Registers rules that refuse or warn on a git command before it runs — a pattern-based command policy applied at the shadow binary, so it covers every invocation through it. The veto evolution of zintercept's around-advice, promoted to a first-class policy layer no VCS has natively.

A rule is an action (deny or warn), a glob pattern matched against the whole command line (* and ?, same matcher as zintercept), an optional repo-state predicate, and an optional message. git zguard deny 'push*--force*' refuses a force-push; git zguard warn 'rm*-rf*' warns but allows.

The --when <predicate> conditions a rule on the current repository: detached (HEAD is detached), dirty (uncommitted changes), protected (HEAD is main or master), unsigned (a commit with no -S/--gpg-sign and commit.gpgsign unset). So git zguard deny 'commit*' --when detached blocks commits on a detached HEAD, and --when unsigned requires signed commits.

list shows the rules; rm <id> removes one; clear removes all; test <cmd>... reports the verdict (DENY/WARN/allow) for a command without running it. Rules are stored in $ZVCS_HOME/guards.tsv (machine-wide); the dispatch hot path is a single stat when no rule is set. The zguard/zpolicy verbs are exempt from their own rules, so a bad rule can never lock you out.

git zpolicy alias of git zguard (command policy)

git zpolicy deny|warn <pattern> [--when <predicate>] [-m <msg>] | list | rm <id> | clear | test <cmd>...

An alias for git zguard — declarative fleet-wide command policy. See git help zguard for the full description.

git zppid per-process commit tally, attributed to the durable process

git zppid [--json]

Reports which process is responsible for each recorded commit, found by walking up past the throwaway per-command shells to the durable agent, program, or login shell that drove them.

Each row carries the pid, its command and working directory, whether it is still alive, and how many commits it landed.

git zprocs per-process breakdown of mutating commands

git zprocs [--json]

Reports how many of each mutating verb — commit, push, add, merge, rebase and the rest — every recorded process has run, attributed the same way as git zppid.

With --json the rows are emitted as NDJSON — one object per line — like every other machine-readable listing.

git zprecache precompute the log caches for recent commits

git zprecache [-n <commits>] [-q]

Fills the ledger's log caches — commit abbreviations and the per-file line tallies that --stat, --numstat, --shortstat and --name-status need — for the newest commits, so those formats read the ledger instead of the object store.

Everything it stores is a pure function of immutable objects, so an entry never expires. -n sets how many commits to walk (default 200); -q suppresses the count.

The daemon does this on its own whenever a watched repository's refs move (zvcs.precache, on by default); this verb is the same pass on demand, for a fresh clone or a fetch that landed while the daemon was down.