Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

CLI contracts

git-std exposes versioned machine contracts for pinned-binary integrations. Machine output is exactly one JSON document on stdout. Human explanations and logs use stderr and can be ignored by a machine consumer.

The CLI schema version is 1.0.0 and is independent of the executable’s tool_version. Additive fields and new diagnostic codes may be introduced in a minor git-std release. Removing or renaming fields, changing their types, or changing documented exit semantics requires a new major CLI schema and a changelog callout.

git std lfs install is a human-oriented setup command. It reports progress and failures on stderr and has no JSON output contract. The resulting LFS entry is an ordinary declarative pre-push command and appears in the existing hook list and hook run contracts.

Inventory

CommandContractExample
git std version --format jsonschemas/v1/cli/version.schema.jsonschemas/v1/cli/examples/version.json
git std bump --dry-run --format jsonschemas/v1/cli/bump.schema.jsonschemas/v1/cli/examples/bump.json
git std lint --format jsonschemas/v1/cli/lint.schema.jsonschemas/v1/cli/examples/lint.json
git std lint --format sarifSARIF 2.1.0Registered codes are ruleId values with matching driver rule descriptors.
git std hook list --format jsonschemas/v1/cli/hook-list.schema.jsonschemas/v1/cli/examples/hook-list.json
git std hook run <hook> --format jsonschemas/v1/cli/hook-run.schema.jsonschemas/v1/cli/examples/hook-run.json
git std doctor --format jsonschemas/v1/cli/doctor.schema.jsonschemas/v1/cli/examples/doctor.json
git std registry --format jsonschemas/v1/cli/registry.schema.jsonschemas/v1/cli/examples/registry.json
git std tag <commit> --format jsonschemas/v1/cli/tag.schema.jsonschemas/v1/cli/examples/tag.json

Object responses contain schema_version, tool_version, and status. Compatibility preserves the existing array shape of range lint and hook-list output; each nonempty array entry carries its own contract metadata. An empty range or empty hook registry remains [].

Exit classes and diagnostics

  • exit 0: the command completed successfully and lint found no violations.
  • exit 1: a rule finding, health-check failure, or failed plan precondition.
  • exit 2: usage, input/output, repository, or other operational failure.

JSON failures contain an exit_code matching the process exit status and a diagnostics array with stable code, severity, and message fields. SARIF operational failures set executionSuccessful = false. For range lint, JSON preserves its array contract and returns [] for an empty reversed range; SARIF emits the GITSTD-LINT-EMPTY-RANGE finding instead. An ordinary empty SARIF range is a successful empty result document. git std registry --format json is the source of truth for rule explanations, diagnostic codes, and the convention resolved from the current project. The same standard-commit rule definitions produce registry entries and lint codes.

Bump plans

Single-version mode (monorepo = false) treats the version selected from the tag lineage as canonical. version_observations reports readable manifests, including inherited and pinned Cargo workspace members. version_mismatches makes disagreement explicit; it does not silently choose a different release per manifest.

A dry-run returns a plan_id over canonical serialized inputs and declared effects. Inputs cover normalized options, HEAD, branch, tags, remotes, effective date, effective and raw configuration, planned version and lock files, lifecycle-hook definitions, GIT_STD_SKIP_HOOKS, PATH, and resolved ecosystem tools. Repeating the same dry-run with unchanged inputs produces the same ID.

To bind apply to that observation:

plan_id="$(git std bump --dry-run --format json | jq -r .plan_id)"
git std bump --expect-plan "$plan_id" --format json --yes

Mutating bumps first require a clean index and working tree as reported by Git. Staged, unstaged, nonignored untracked files and dirty submodules cause exit 1 with GITSTD-BUMP-DIRTY, including edits to bound manifests, configuration or hooks. This admission check precedes plan comparison; dry-run remains available on a dirty working tree.

After clean admission, --expect-plan <plan-id> recomputes the plan before built-in mutation. If any bound input changed, apply exits 1 with GITSTD-BUMP-PLAN-DIVERGED; it does not update version files, changelog, commit, tag, or push. The plan is not stored on a server: the ID is a content-derived precondition. It conflicts with --dry-run because it is meaningful only for apply.

Effects declare one of four fidelity levels:

  • exact: git-std predicts bytes and includes before/after SHA-256 when known.
  • runtime: the effect is deterministic, but its identifier is observed after apply; results include commit and annotated-tag OIDs.
  • conditional: external tools, locks, network, or remote state determine the result.
  • opaque: an arbitrary lifecycle hook may perform undeclared external effects.

fidelity.exact is false whenever a conditional or opaque effect exists, and limitations explains why. A guarded apply prevents stale built-in changes; it cannot make arbitrary hook or remote effects transactional. Final comparison of declared and observed effects belongs to the calling orchestrator. When GIT_STD_SKIP_HOOKS is enabled, that state is bound into inputs.options and hook effects are omitted from the plan.

Monorepo JSON remains available with v1 metadata but does not claim this single-version fidelity model and does not support --expect-plan. Consumers requiring one canonical project version and guarded apply must use monorepo = false. Stable-branch mode does not expose versioned JSON; it rejects --format json instead of silently claiming incomplete fidelity.

Released-version evidence

Release v0.11.15 is evidence for the legacy command spellings and successful JSON fields only. The v1 metadata, registry, SARIF, mismatch facts, plan ID, and --expect-plan guard are absent from the published v0.11.15 binary. Until the workspace version is bumped for the next release, branch builds and examples still report the source package version 0.11.15; that field alone is not release evidence. Record the first release containing the contracts here after a real release is published and verified.

Tag results

tag reports the pinned target_oid, release_branch, selected remote, dry_run, and each tag’s name, version, object ID, planned action, local state, remote state, signature state, and version source. Dry-run performs inspection without creating refs. A successful retry can report existing tags without creating new objects. See release workflows for recovery.

Exit 1 refuses an unsafe or inconsistent release. Exit 2 reports operational failure, including partial local creation or uncertain publication. Inspect per-tag states and repeat the same explicit commit after resolving the cause; do not infer that exit 2 means the remote received nothing.

Per-tag local states are missing, existing, adopted, created and conflict. Remote states are not_checked, missing, existing, pushed, conflict and unknown. action is create, adopt or none; it describes the plan separately from observed state. version_basis is manifest or release_subject. An early failure may leave the target or branch unresolved and the tags array empty.

Signature results currently emitted are unsigned, verified and unverified. verified requires a successful git verify-tag; any unsuccessful verification is unverified, with Git’s explanation retained in a diagnostic. The schema also allows invalid, but the command does not currently distinguish cryptographic failure from unavailable verification or trust configuration. A signed tag may therefore satisfy --sign without establishing signer trust.

Runtime refusals use GITSTD-TAG-REFUSED; operational errors use GITSTD-GIT-OPERATION. Warnings, including configuration and signature-trust notes, use GITSTD-TAG-NOTE. Human output uses stderr and JSON uses stdout. A no-op text success is silent; JSON still reports the satisfied plan.