docs: sha256:bd58aa96f2ed23218e823e8bb60da938ce95c3ec8bf6658bb1317873a460720b · gabriel/muse

docs: fix systemic --format→--json drift and broken plumbing-namespace sentence in plumbing.md

Root cause: every command's real -h output uses a boolean --json/-j flag, but plumbing.md documented a nonexistent --format/-f value flag (json|text, raw|info, etc.) throughout all ~24 commands, plus "Output — --format text" section headers and exit-code entries like "bad --format". This mirrors the same fiction already found and removed from ls_remote.py's own docstring, reflog.md, and remotes.md in prior commits on this branch's history — this file was the last of the three docs still carrying it, and had it in every single command section rather than a couple of examples.

Also fixed the doc's own broken intro sentence, which read "previously namespaced under `muse <cmd>` and are now top-level: `muse <cmd>`" — identical text on both sides of "and are now", from a careless prior find-replace that stripped the word "plumbing". Now reads "previously namespaced under `muse plumbing <cmd>`".

Verified every command individually via `muse <cmd> -h` against the live 0.2.1rc4 binary (not pattern-matched) and found real drift beyond --format→--json: - Object IDs are now the canonical `sha256:<hex>` prefixed form everywhere, not bare hex. - All --json output is wrapped in a common envelope (muse_version, schema, exit_code, duration_ms, timestamp, warnings) — documented once up top rather than repeated in every example. - Several commands gained flags not documented at all: --stdin (many), --dry-run (pack-objects), --old-value CAS guard (update-ref), --agent-id/--model-id/--toolchain-id (commit-tree), --count (show-ref), --no-commits (for-each-ref), --create-branch (symbolic-ref), --rules/--invalid-only (check-ref-format), --patterns-only/--ignored-only (check-ignore), --rules-only/--unmatched-only (check-attr), --domain/--capabilities-only (domain-info), --raw/--only/--path-prefix (snapshot-diff), --strict/--stat (verify-pack), --fields (read-commit), --no-manifest/--path-prefix (read-snapshot), --inline/--batch/--batch-check (cat-object), --all/--fail-fast (verify-object), --abbrev-ref (rev-parse). - unpack-objects/verify-pack output field names changed (objects_written -> blobs_written+tags_written; objects_checked -> blobs_checked, plus new promised_objects/base_objects/bundle_mode/base_commits for the promisor remote model). - Several commands default to plain text, not JSON (ls-remote, show-ref, read-snapshot, verify-object, domain-info, symbolic-ref, for-each-ref, name-rev, check-ref-format, check-ignore, check-attr) — only hash-object, cat-object, rev-parse, read-commit, ls-files, commit-tree, update-ref, commit-graph, merge-base, snapshot-diff, pack-objects, unpack-objects default the other way or accept --json as the only structured option.

Removed every exit-code table entry mentioning "bad --format" since there is no format value left to validate; --json is a boolean, not a choice flag.

Verified with: grep -n "muse plumbing \|--format" docs/reference/plumbing.md -> only the two intentional literal mentions remain (corrected intro sentence, and the paragraph explicitly stating --format does not exist). No test suite references this markdown file's content.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

~41

symbols modified

file changed

1185

files in snapshot

dead code introduced

Semantic Changes 41 symbols

~ docs/reference/plumbing.md .md 41 symbols modified

~ Muse Low-level Commands Reference

~ Command Reference

~ cat-object — read a stored object

~ commit-graph — emit the commit DAG

~ commit-tree — create a commit from a snapshot ID

~ hash-object — compute a content ID

~ ls-files — list files in a snapshot

~ ls-remote — list refs on a remote

~ pack-objects — pack commits for transport

~ read-commit — print full commit metadata

~ read-snapshot — print full snapshot metadata

~ rev-parse — resolve a ref to a commit ID

~ unpack-objects — apply an mpack to the local store

~ update-ref — move a branch to a commit

~ Composability Patterns

~ Composability Patterns — Advanced

~ Audit all refs with full metadata and filter by recency

~ Check which files changed between two branches

~ Find stale branches (no commits in the last 30 days)

~ Name every commit reachable from a branch

~ Switch active branch via plumbing

~ Verify a bundle before shipping

~ Export a history range

~ Inspect what changed in the last commit

~ Script a bare commit (advanced)

~ Ship commits between two machines

~ Verify a stored object

~ check-attr — query merge-strategy attributes for paths

~ museignore

~ check-ref-format — validate branch and ref names

~ domain-info — inspect the active domain plugin

~ for-each-ref — iterate all refs with rich commit metadata

~ merge-base — find the common ancestor of two commits

~ name-rev — map commit IDs to branch-relative names

~ show-ref — list all branch refs

~ snapshot-diff — diff two snapshot manifests

~ symbolic-ref — read or write HEAD's symbolic reference

~ verify-object — re-hash stored objects to detect corruption

~ verify-pack — verify MPack integrity

~ Object ID Quick Reference

~ The Plumbing Contract

Files Changed

1185 in snapshot

~ docs/reference/plumbing.md .md

← Older Oldest on docs/fix-plumbing-format-drift

All commits

Newer → Latest on docs/fix-plumbing-format-drift

0 comments

No comments yet. Be the first to start the discussion.

To add a comment, use the Muse CLI: muse hub commit comment sha256:bd58aa96f2ed23218e823e8bb60da938ce95c3ec8bf6658bb1317873a460720b --body "your comment"