Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

git-std

From commit to release. One tool for conventional commits, versioning, changelog, and git hooks management.

Stop juggling five tools to enforce commit standards, bump versions, and manage hooks. git-std replaces commitizen, commitlint, standard-version, husky, and lefthook with a single, fast binary — zero runtime dependencies.

Features

  • Structured commits — interactive prompt for type, scope, and description, or non-interactive with --message
  • Commit validation — lint messages inline, from file, or across a revision range
  • Version bumping — semver, calver, and patch-only schemes, calculated automatically from commit history
  • Changelog generation — incremental or full, built from conventional commits
  • Git hooks — install, enable/disable, and auto-format staged files safely before commit
  • Lock file sync — automatically update Cargo, npm, yarn, pnpm, deno, uv, and poetry lock files after bump
  • Custom version files — update any file during bump using regex patterns
  • Configuration — .git-std.toml with sensible defaults, inspectable via config list/get
  • Shell completions — bash, zsh, fish
  • AI agent skills — install commit and bump skills for your AI coding agent with upskill add driftsys/git-std
  • CI-ready — JSON output, non-zero exit codes, no interactive prompts in pipelines
  • Versioned automation contracts — JSON Schemas, stable diagnostics, SARIF, and guarded bump apply

Quick start

git std init                         # maintainer: scaffold hooks + bootstrap script
git std commit                       # interactive commit
git std bump                         # bump + changelog + tag
git push --follow-tags

Contributors, after git clone or git worktree add, just run ./bootstrap (generated by git std init).

Invoked as git std via git’s subcommand discovery.

Getting started

Install

Install script (recommended):

curl -fsSL https://raw.githubusercontent.com/driftsys/git-std/main/install.sh | bash

From source:

cargo install git-std

Shell completions:

# Bash (~/.bashrc)
eval "$(git-std --completions bash)"

# Zsh (~/.zshrc)
eval "$(git-std --completions zsh)"

# Fish (~/.config/fish/config.fish)
git-std --completions fish | source

Set up git-std in your repo

Maintainer, one-time setup:

git std init

This scaffolds .githooks/ (hook templates + shims, prompting which hooks to enable — default pre-commit and commit-msg), generates a ./bootstrap script for contributors, creates .git-std.toml, and appends a post-clone reminder to README.md/AGENTS.md. Review the staged changes and commit them.

Contributor, after git clone or git worktree add:

./bootstrap

This runs the environment checks and any project-specific bootstrap commands (via git std bootstrap under the hood).

To set up only hooks without the rest of init — e.g. in a repo that already has a .git-std.toml and bootstrap script — run git std hook install directly.

AI agent skills

Install the std-commit and std-bump skills for your AI coding agent with upskill (cargo install upskill or see its install script):

upskill add driftsys/git-std

Make a commit

Stage your changes and run the interactive builder:

git add .
git std commit

Or use non-interactive mode:

git std commit -m "feat(auth): add OAuth2 PKCE flow"

Validate commits

git std lint "feat: add login"
git std lint --range main..HEAD

Use --strict to enforce types and scopes from .git-std.toml.

Preview changelog

git std changelog --stdout

Bump, changelog, and tag

git std bump
git push --follow-tags

This analyses commits since the last tag, calculates the next version, updates version files, generates the changelog, creates a release commit, and tags it.

Use --dry-run to preview without writing anything.

Release management

See release workflows for the preferred combined commit-and-tag process and the supported prepare-then-tag process. Agents use std-bump for both release preparation and finalizing an already merged release.

Commands

git std <command> [options]

Global Flags

FlagDescription
--help / -hPrint help
--version / -VPrint version
--color <when>auto (default), always, never
--completions <shell>Generate shell completions to stdout
--updateUpdate git-std to the latest release

git std lint

Validate commit messages against the Conventional Commits specification.

Input modes:

git std lint "feat: add login"                    # inline message
git std lint --file .git/COMMIT_EDITMSG           # from file (strips # comments)
git std lint --range main..HEAD                   # all commits in a range

Flags:

FlagDescription
--file <path>Read message from file
--range <range>Validate all commits in a git revision range
--strictEnforce types/scopes from .git-std.toml
--format <fmt>Output format: text (default), json, or sarif

Exit codes: 0 = valid, 1 = invalid, or an empty --range whose inverse direction has commits, 2 = I/O or usage error.

An empty --range exits 0 — nothing to lint is not a failure. A range git cannot resolve exits 2. An empty range that does not end at the current checkout, and whose inverse direction has commits, exits 1 with a hint naming the inverse range, rather than passing silently. <base>..HEAD always exits 0 when empty, so the gate stays green on a checkout that is behind its base.

With --format json, both empty cases write [] to stdout and the exit code carries the verdict, so a machine consumer always has an array to parse.

Examples:

# Validate a single message
git std lint "feat(auth): add OAuth2 PKCE flow"

# Validate all commits on a branch
git std lint --range main..HEAD

# Strict mode — reject unknown types and scopes
git std lint --strict --range main..HEAD

# As a commit-msg hook
git std lint --file "$1"

# SARIF 2.1.0 with stable rule IDs
git std lint "feat: add login" --format sarif

git std commit

Interactive conventional commit builder. Prompts for type, scope, description, body, and breaking change, then runs git commit.

Flags:

FlagDescription
--type <type>Pre-fill type, skip prompt
--scope <scope>Pre-fill scope, skip prompt
--message <msg>Non-interactive mode
--body <text>Commit body paragraph
--breaking <msg>Add BREAKING CHANGE footer
--footer <text>Add a trailer footer (repeatable)
--signoff / -sAdd Signed-off-by trailer
--dry-runPrint message without committing
--amendPass --amend to git commit
--sign / -SGPG-sign the commit
--all / -aStage tracked changes

Exit codes: 0 = committed, 1 = validation/git error, 2 = usage error.

git std bump

A mutating bump requires a clean working tree and index, including no untracked non-ignored files. Commit or remove pending changes first. This also applies to --no-commit; --dry-run remains available on dirty checkouts. Dirty input fails before hooks or release writes (GITSTD-BUMP-DIRTY, exit 1 in JSON mode). The check overrides hidden-untracked and submodule-ignore settings, but Git index flags such as assume-unchanged can still hide tracked edits. Clear those flags before relying on the clean-state check.

Git-std stages its managed version files, synced lock files, and changelog. Lifecycle hooks must explicitly stage extra release outputs with git add or git rm. The release commit includes the resulting index, including hook-staged additions, modifications, and deletions. Unstaged extra outputs are left out. post-bump runs after the release commit and cannot add files to it.

With --no-commit, release finalization skips staging, committing, and tagging; any staging done by hooks remains. Stable-branch setup still creates its separate configuration commit. Failures preserve files and staged changes for inspection, so restore a clean state before retrying. Hook effects remain opaque in previews.

Calculate the next version from conventional commits, update version files, generate changelog, commit, and tag.

Flags:

FlagDescription
--dry-runPrint plan without writing
--prerelease [tag]Bump as pre-release (e.g. 2.0.0-rc.1)
--release-as <ver>Force a specific version, or patch/minor/major to force that bump level (e.g. when no bump-worthy commits exist)
--first-releaseInitial changelog, no bump
--first-major-releaseConfirm an intentional 0.x → 1.0 promotion (required whenever a bump would cross that boundary)
--no-tagSkip tag creation
--no-commitUpdate files only
--sign / -SGPG-sign commit and tag
--skip-changelogBump without changelog
--forceAllow breaking changes in patch-only scheme
--stable [branch]Create a stable branch for patch-only releases
--minorUse minor bump (instead of major) when advancing main after stable
--format <fmt>Output format: text (default) or json
--package <name>Filter bump to specific package(s) (monorepo only, repeatable)
--push [remote]Push commit and tags after release (default remote: origin)
--yes / -ySkip branch confirmation prompt
--expect-plan <id>Apply only if current inputs reproduce a prior dry-run plan ID

Exit codes: 0 = success, 1 = error.

For a guarded single-version apply (monorepo = false):

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

Monorepo bump

When monorepo = true, each package is versioned independently based on commits touching its path.

# Bump all packages with changes
git std bump

# Preview monorepo bump
git std bump --dry-run

# Bump specific package(s)
git std bump -p core
git std bump -p core -p cli

# JSON output for CI
git std bump --dry-run --format json

Dependency cascade: when package A bumps and package B depends on A, B gets at least a patch bump. Use -p to skip cascade and bump only the named packages.

git std changelog

Reference footers (Refs, Closes, Fixes, Resolves) contribute only a leading list of references. Supported values are local issue numbers (#123 or 123), qualified repository references (owner/repo#123), HTTP(S) URLs, and external tracker IDs such as PROJ-123. Commas or whitespace separate references; continuation lines are accepted until a blank line or non-reference prose. Pasted commit bodies after that boundary are not copied into changelog entries. Qualified repository references remain plain text and never become local links. External tracker IDs continue to use the configured bug_url template. In commit descriptions, issue numbers inside URL fragments remain unchanged; local issue references after completed Markdown links still become local links.

Identical breaking notes appear once per release, in first occurrence order. Equality uses the exact parsed text: case, punctuation, and internal whitespace remain significant. Multiline notes and their paragraphs are preserved. These rules apply both to changelog and the changelog generated by bump; conventional commit footer parsing is unchanged.

Generate or update the changelog from git history.

Flags:

FlagDescription
--fullRegenerate entire changelog
--range <range>Generate for a tag range (e.g. v1..v2)
-w, --write [path]Write to file (default: CHANGELOG.md)

Output goes to stdout by default. Pass -w / --write to write to CHANGELOG.md, or -w <path> for a custom path. --full and --range are mutually exclusive. Without either, generates an incremental changelog from unreleased commits since the last tag.

git std init

Scaffold hooks, bootstrap script, and README section in one step. Consolidates hook setup and bootstrap scaffolding for maintainers.

git std init              # scaffold everything interactively
git std init --force      # overwrite existing files
git std init --refresh    # merge config defaults without overwriting hooks

What it does:

  1. Creates .githooks/ directory.
  2. Sets core.hooksPath to .githooks.
  3. Writes .hooks templates (pre-commit, commit-msg, pre-push, etc.).
  4. Prompts which hooks to enable, writes shims.
  5. Generates ./bootstrap script.
  6. Generates .githooks/bootstrap.hooks.
  7. Creates .git-std.toml with taplo schema directive (if absent).
  8. Appends post-clone section to README.md and AGENTS.md (if found).
  9. Stages all created files.

If LFS rules are detected during interactive setup, init offers to configure Git LFS and add its pre-push command. Non-interactive setup leaves LFS disabled; run git std lfs install explicitly after init when needed.

To install AI agent skills for git std, use upskill (upskill add driftsys/git-std) — init does not scaffold skills.

Flags:

FlagDescription
--forceOverwrite existing files
--refreshMerge config defaults without overwriting hooks

Exit codes: 0 = success, 1 = error.

git std lfs install

Configure Git LFS for a repository already managed by git std init:

git std lfs install

This explicit maintainer command runs git lfs install --local --skip-repo, adds ! [delete] git lfs pre-push "$@" to .githooks/pre-push.hooks once, and enables the managed pre-push hook. It works even when the current checkout has no LFS rule. Other pre-push commands stay in place. Commit the changed hook file and shim so contributors receive the integration.

To disable LFS uploads while keeping other pre-push checks, comment out the LFS line. Running git std lfs install again restores it. To disable all pre-push commands, use git std hook disable pre-push. Bootstrap does not change these choices. A custom pre-push shell hook needs manual integration; the installer will not replace it. GIT_STD_SKIP_HOOKS=1 bypasses all managed hook commands, including LFS upload.

git std hook

Manage git hooks defined in .githooks/*.hooks files.

git std hook run <hook>       # execute a hook manually
git std hook list             # display configured hooks
git std hook enable <hook>    # activate a hook (rename .off → shim)
git std hook disable <hook>   # deactivate a hook (rename shim → .off)

Subcommands:

SubcommandDescription
run <hook>Execute a hook manually
listDisplay all hooks with enabled/disabled status
enable <hook>Activate a disabled hook
disable <hook>Deactivate an enabled hook

Known hook types: pre-commit, commit-msg, pre-push, post-commit, prepare-commit-msg, post-merge.

For pre-push, commands skip pushes that contain only ref deletions. Add [delete] after the optional failure prefix when a command must also run for those pushes:

! cargo test --workspace
! [delete] ./scripts/check-ref-policy.sh

Normal and mixed pushes run every command. Each executed command receives the remote name as $1, the remote URL as $2, and both values through $@. Each command also receives an independent copy of the complete pre-push ref update list on standard input.

Flags (run and list):

FlagDescription
--format <fmt>Output format: text (default), json

git std bootstrap

Post-clone environment setup. Detects convention files and configures the local environment.

git std bootstrap              # run built-in checks + bootstrap.hooks
git std bootstrap --dry-run    # print what would be done

Built-in checks:

Convention fileAction
.githooks/git config core.hooksPath .githooks
.gitattributesLocal LFS filters + git lfs pull (if filter=lfs)
.git-blame-ignore-revsgit config blame.ignoreRevsFile .git-blame-ignore-revs

After built-in checks, runs .githooks/bootstrap.hooks if present. Bootstrap scans root and nested .gitattributes files for filter=lfs. With managed hooks, it uses git lfs install --local --skip-repo and preserves the tracked pre-push policy. Detection does not inspect other branches or historical commits, so uploads are controlled by the explicit hook entry rather than a per-push attribute check.

Flags:

FlagDescription
--dry-runPrint what would be done without acting

git std doctor

Show everything about your local git-std setup in one command. Three sections: Status, Hooks, Configuration. Problems appear as hints at the bottom. When LFS rules are declared, doctor checks for an active managed LFS pre-push entry. It reports custom pre-push wrappers as unverified.

git std doctor              # show all sections, exit 0 (no problems) or 1
git std doctor --format json  # machine-readable JSON on stdout

Sections:

SectionContents
StatusTool versions: git, git-lfs (if .gitattributes needs it), git-std with update notice if available
HooksAll .githooks/*.hooks files with commands and sigils (! required, ? advisory), enabled/disabled state
ConfigurationAll .git-std.toml keys; explicit values in bold, defaults plain/dim

Example output:

  Status
    git 2.43.0
    git-lfs 3.4.1
    git-std 0.11.3 (update available: 0.12.0)

  Hooks
    commit-msg
      !  git std lint -f
    pre-commit
      !  cargo fmt --check
      !  cargo clippy
    pre-push (disabled)
      !  just verify

  Configuration
    scheme           semver
    strict           true
    ...

  hint: git-lfs not found — required by .gitattributes
  hint: .git-std.toml invalid: expected `=` at line 3

Flags:

FlagDescription
--format <fmt>Output format: text (default), json

Exit codes: 0 = no problems, 1 = one or more hints surfaced, 2 = not a git repository.

git std version

Lightweight, scriptable version queries.

git std version                  # 0.11.3
git std version --describe       # 0.11.3-dev.7+g3a2b1c.dirty
git std version --next           # 0.12.0
git std version --label          # minor
git std version --code           # 10299
git std version --format json    # all fields as JSON

Output goes to stdout. No v prefix.

Flags:

FlagDescription
--describeCargo-style describe: -dev.N pre-release + +hash[.dirty] metadata
--nextNext version from conventional commits since the last tag
--labelBump label (major/minor/patch/none), accounting for pre-1.0
--codeInteger version code
--format <fmt>Output format: text (default), json

Exit codes: 0 = success, 1 = error.

git std registry

Inspect stable lint rules, diagnostic codes, explanations, and the effective project convention used by machine integrations:

git std registry --format json

See CLI contracts for schemas, exit classes, compatibility, and bump plan fidelity.

--completions <shell>

Generate shell completion scripts to stdout. The output includes wrappers that enable completion for both git-std and git std invocations. Works without a subcommand — usable regardless of install method.

git std --completions bash   # Bash
git std --completions zsh    # Zsh
git std --completions fish   # Fish

Add to your shell profile:

# Bash (~/.bashrc)
eval "$(git-std --completions bash)"

# Zsh (~/.zshrc)
eval "$(git-std --completions zsh)"

# Fish (~/.config/fish/config.fish)
git-std --completions fish | source

Update Check

git-std periodically checks for newer releases in the background and prints a hint after command output when an update is available.

  • Non-blocking — a detached background process fetches the latest release once every 24 hours.
  • Adapts to install method (cargo, install.sh, nix).
  • Opt-out: GIT_STD_NO_UPDATE_CHECK=1.

git std tag

Tag an existing release commit without another bump. The explicit <commit> argument identifies a release reachable from the configured release branch.

OptionPurpose
--dry-runValidate the exact plan without creating refs
--branch <name>Override the release branch
--package <name>Select a released package; repeat for several
--signCreate signed annotated tags
--push <remote>Publish only the planned tags atomically
--format <text|json>Select human or versioned machine output

The command reads configuration and versions from the target commit and leaves HEAD, the index and working files unchanged. It reuses matching annotated tags, refuses conflicts, and reports partial or uncertain outcomes without rollback. With --push, it verifies remote branch reachability and exact remote tag objects.

See release workflows for preflight requirements, both release processes, retry behavior and limitations. See CLI contracts for structured results and exit semantics.

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.

Release integrity

Pinned-binary integrations should download GitHub Release assets directly and verify the complete evidence set before executing the binary. install.sh and cargo install git-std remain standalone convenience flows for human use.

Targets and asset set

PlatformTarget
Linux x86-64x86_64-unknown-linux-musl
Linux ARM64aarch64-unknown-linux-musl
macOS x86-64x86_64-apple-darwin
macOS Apple Siliconaarch64-apple-darwin
Windows x86-64x86_64-pc-windows-msvc

For every target, a release publishes this inseparable set:

git-std-<target>.tar.gz
git-std-<target>.tar.gz.sha256
git-std-<target>.tar.gz.sigstore.json
git-std-<target>.tar.gz.spdx.json
git-std-<target>.tar.gz.provenance.sigstore.json

The archive contains git-std (git-std.exe for Windows) and generated man pages at its root. The checksum names the exact archive bytes. The SPDX 2.3 document records the archive name, release version, and SHA-256 digest. The signature bundle is a keyless Sigstore blob signature. The provenance bundle is generated by GitHub artifact attestations with the archive as its subject.

Local verification

Local verification is offline and does not establish signer identity:

scripts/release/verify.sh git-std-<target>.tar.gz vX.Y.Z

It checks the allowed target name, archive layout, checksum, SPDX version and subject data, and JSON shape/presence of both Sigstore bundles. The release test suite proves success and rejection of altered bytes, checksums, SBOM metadata, and missing bundles:

just test-release

Hosted verification

Hosted verification additionally checks the transparency-log certificate and GitHub provenance identity:

scripts/release/verify.sh git-std-<target>.tar.gz vX.Y.Z --hosted

This invokes cosign verify-blob with the repository workflow identity and gh attestation verify with the saved provenance bundle. It requires Cosign, GitHub CLI, network access, and evidence generated by GitHub Actions.

The release workflow is designed for SLSA Build Level 2: a hosted build service generates signed provenance for the exact artifact. This branch has only local verification, so its achieved level is not yet claimed. Claim Build Level 2 for a version only after the hosted workflow and attestation verification succeed.

Real-release verification

A real-release check confirms facts local tests cannot:

  1. all five jobs cross-build successfully;
  2. OIDC keyless signing and transparency-log inclusion succeed;
  3. GitHub stores and verifies each provenance attestation;
  4. the GitHub Release exposes all 25 expected files without renaming; and
  5. downloaded bytes pass hosted verification independently.

Manual workflow_dispatch runs build and evidence generation but never create a Release or publish crates. Only a v* tag enables those jobs.

Release v0.11.15 has archives and .tar.gz.sha256 files for all five targets, but no Sigstore, SPDX, or provenance companions. The enhanced evidence set is unreleased on this branch. Update this mapping after the first verified release; do not infer conformance from a closed issue or a successful local test.

Collecting generated man pages

Release builds capture Cargo JSON messages and match the git-std binary’s manifest to the workspace package. The collector uses that package’s build-script-executed.out_dir to locate generated man pages. It does not search Cargo’s private build directory layout, which changed in Cargo 1.100. Custom target and build directories therefore do not require new globs. For cross v0.2.5, the collector maps the container’s /target and /project mounts to the host directories reported by Cargo metadata.

Collection requires a successful build, one matching build-script output, and the main git-std.1 page. Missing or ambiguous outputs fail packaging; other build directories cannot supply fallback pages. Previously staged man pages are replaced. Signature, provenance, checksum, and smoke gates remain required before publication.

Run just test-release for layout and rejection fixtures. Before publishing a packaging correction, dispatch the release workflow on its reviewed branch and require all five target builds and smoke jobs to pass. Manual dispatch runs the integrity gates without creating a release or publishing crates.

Recipes

Git aliases

Shorten common commands with git aliases:

git config --global alias.sc "std commit"
git config --global alias.sb "std bump"
git config --global alias.sl "std changelog"
git config --global alias.sk "std check"

Then use:

git sc           # interactive commit
git sc -am "fix(auth): handle expired tokens"
git sk --range main..HEAD
git sl --stdout  # preview changelog
git sb           # bump + changelog + tag

Semver workflow

Semver is the default scheme — no configuration needed.

Bump rules are inferred from conventional commits:

  • BREAKING CHANGE or ! suffix → major
  • feat → minor
  • fix / perf / revert → patch
  • docs / style / refactor / test / chore / ci / build → no bump

This matches the Conventional Commits spec and isn’t configurable. If no commits warrant a bump but you still want a release (e.g. a docs-only change), force the level explicitly:

git std bump               # auto-detect bump type
git std bump --dry-run     # preview without writing
git std bump --prerelease  # e.g. 2.0.0-rc.1
git std bump --release-as 3.0.0  # force a specific version
git std bump --release-as patch  # force a patch bump with no bump-worthy commits

Calver workflow

Set the scheme in .git-std.toml:

scheme = "calver"

[versioning]
calver_format = "YYYY.0M.PATCH"

Commit types are ignored — the version is derived from the current date. The patch counter increments within the same period and resets when the period changes.

# March 2026, first release of the month
git std bump          # → 2026.03.0

# March 2026, second release
git std bump          # → 2026.03.1

# April 2026, first release
git std bump          # → 2026.04.0

Common formats:

FormatExampleUse case
YYYY.MM.PATCH2026.3.0Monthly releases
YYYY.0M.PATCH2026.03.0Zero-padded
YY.WW.DP26.12.30Weekly + day
YYYY.MM.DD.PATCH2026.3.18.0Daily releases

Stable branch

Use --stable to create a patch-only maintenance branch from the current version:

# On main at v2.3.0
git std bump --stable

This creates a stable/v2.3 branch where only patch bumps are allowed. Breaking changes are rejected unless --force is used.

# On stable/v2.3 — cherry-pick a fix, then:
git std bump          # → 2.3.1
git std bump          # → 2.3.2

Back on main, use --minor to advance without a major bump:

# On main after stable branch was cut
git std bump --minor  # → 2.4.0 (instead of 3.0.0)

Custom version files

By default, git std bump auto-detects and updates Cargo.toml version fields. For other files, add [[version_files]] entries to .git-std.toml. Each entry needs a file path and a regex whose first capture group matches the version string.

Plain text version file:

[[version_files]]
path = "VERSION"
regex = '(.+)'

Java (pom.xml):

[[version_files]]
path = "pom.xml"
regex = '<version>([^<]+)</version>'

Helm chart:

[[version_files]]
path = "Chart.yaml"
regex = 'version:\s*(.+)'

Python (pyproject.toml):

[[version_files]]
path = "pyproject.toml"
regex = 'version\s*=\s*"([^"]+)"'

Multiple files at once:

[[version_files]]
path = "package.json"
regex = '"version":\s*"([^"]+)"'

[[version_files]]
path = "src/version.h"
regex = '#define\s+VERSION\s+"([^"]+)"'

Glob pattern (many similar files):

[[version_files]]
path = "skills/*/SKILL.md"
regex = 'version:\s*(\S+)'

A path containing * ? [ { is treated as a glob and expanded against every matching file, sharing the same regex. See CONFIG.md for details on glob syntax and warning behavior.

These are updated alongside auto-detected files during git std bump. Use --dry-run to preview which files would be updated.

Monorepo workflow

Enable per-package versioning for multi-package repositories:

monorepo = true
scheme = "semver"
scopes = "auto"

[versioning]
tag_template = "{name}@{version}"

# Optional — auto-discovered from workspace manifests if omitted
# [[packages]]
# name = "core"
# path = "crates/core"

Packages are auto-discovered from Cargo.toml workspace members, package.json workspaces, or deno.json workspace.

Bump all packages

git std bump                   # bumps all packages with changes
git std bump --dry-run         # preview what would change

Bump specific packages

git std bump -p core           # bump only core
git std bump -p core -p cli    # bump core and cli

The -p flag skips dependency cascade — only the named packages are bumped.

Per-package scheme override

Mix versioning schemes in the same monorepo:

monorepo = true
scheme = "semver"              # default for all packages

[versioning]
tag_template = "{name}@{version}"
calver_format = "YYYY.0M.PATCH"

[[packages]]
name = "core"
path = "crates/core"

[[packages]]
name = "api"
path = "crates/api"
scheme = "calver"              # this package uses calver

Per-package changelog config

Override changelog settings per package:

[[packages]]
name = "core"
path = "crates/core"

[packages.changelog]
hidden = ["chore"]             # show more commit types for core

Each package gets its own CHANGELOG.md in its root directory (e.g. crates/core/CHANGELOG.md). The root CHANGELOG.md includes all commits from all packages.

Git hooks

Setting up hooks

git std hook install

This writes .githooks/*.hooks template files and shim scripts, sets core.hooksPath, and prompts which hooks to enable.

Hook types

HookWhen it runsTypical use
pre-commitBefore a commit is createdLint, format, run fast tests
commit-msgAfter the message is writtenValidate conventional commit
prepare-commit-msgBefore the editor opensPre-fill commit template
post-commitAfter the commit is createdNotifications, stats
pre-pushBefore push sends data to remoteFull test suite, build validation
post-mergeAfter a merge completesReinstall deps, rebuild

Command prefixes

Each .hooks file contains one command per line with a prefix that controls behaviour:

PrefixNameBehaviour
!checkRun command, block on failure
~fixIsolate staged files, run, re-stage
?advisoryRun command, never block

The ~ prefix safely isolates staged content, runs the formatter, and re-stages the result. $@ is populated with the list of staged files.

pre-commit: lint only

Check formatting and lint without modifying files. The commit is blocked if any check fails.

.githooks/pre-commit.hooks:

! cargo fmt --check -- $@
! cargo clippy --workspace -- -D warnings

pre-commit: auto-format

Automatically format staged files and re-stage the result. The ~ prefix handles the stash dance so unstaged changes are preserved.

.githooks/pre-commit.hooks:

~ cargo fmt -- $@
! cargo clippy --workspace -- -D warnings
? cargo test --workspace

This formats first, then lints (blocking), then runs tests (advisory — never blocks the commit).

commit-msg: validate message

Reject commits that don’t follow conventional commits.

.githooks/commit-msg.hooks:

! git std lint --file {msg}

pre-push: PR readiness check

Run the full validation suite before pushing. Catches issues before CI does.

.githooks/pre-push.hooks:

! cargo test --workspace
! cargo clippy --workspace -- -D warnings
! git std lint --range origin/main..HEAD
! [delete] ./scripts/check-ref-policy.sh

Deletion-only pushes skip the first three checks. The [delete] command also runs for those pushes, which is useful for local ref policy checks. Normal and mixed pushes run all four commands.

Managing hooks

git std hook enable pre-push
git std hook disable post-commit
git std hook list              # see status of all hooks

Release management

See release workflows for the preferred combined commit-and-tag process and the supported prepare-then-tag process. Agents use std-bump for both release preparation and finalizing an already merged release.

git-std — Configuration

git-std reads .git-std.toml in the project root. All fields are optional — sensible defaults are used when the file is absent or a field is omitted.

Editor schema

A JSON Schema is available for validation and autocomplete in any JSON Schema-aware TOML editor.

Add the $schema key to your .git-std.toml:

"$schema" = "https://driftsys.github.io/git-std/schemas/v1/git-std.schema.json"

Or use a taplo inline directive (does not modify the file):

#:schema https://driftsys.github.io/git-std/schemas/v1/git-std.schema.json

Full schema

# ── Project ───────────────────────────────────────────────────────
scheme = "semver"                              # semver | calver | patch
types = ["feat", "fix", "docs", "style",
         "refactor", "perf", "test",
         "chore", "ci", "build", "revert"]
scopes = ["auth", "api", "ci", "deps"]         # "auto" | string[] | omit
strict = true                         # enforce types/scopes
monorepo = false                      # per-package versioning
release_branch = "main"               # expected branch for bumps
refs_required = ["feat", "fix"]       # types that require a footer ref

# ── Versioning ────────────────────────────────────────────────────
[versioning]
tag_prefix = "v"                               # git tag prefix
prerelease_tag = "rc"                          # default pre-release id
calver_format = "YYYY.MM.PATCH"                # only when scheme = "calver"
tag_template = "{name}@{version}"              # per-package tag format

# ── Changelog ─────────────────────────────────────────────────────
[changelog]
title = "Release Notes"                        # optional, custom heading
hidden = ["chore", "ci", "build", "style", "test"]
bug_url = "https://github.com/org/repo/issues" # optional, issue link base

[changelog.sections]
feat = "Features"
fix = "Bug Fixes"
perf = "Performance"
refactor = "Refactoring"
docs = "Documentation"

# ── Version files ────────────────────────────────────────────
[[version_files]]
path = "pom.xml"
regex = '<version>([^<]+)</version>'

# ── Packages (monorepo) ─────────────────────────────────────
[[packages]]
name = "core"
path = "crates/core"
# scheme = "patch"                             # optional override

Fields

Top-level

FieldTypeDefaultDescription
schemestring"semver"Versioning scheme (see below)
typesstring[]11 standard typesAllowed conventional commit types
scopes"auto" or string[]NoneScope discovery or explicit allowlist
strictboolfalseEnforce types/scopes validation without --strict flag
monorepoboolfalseEnable per-package versioning
release_branchstring(none)Branch that git std bump is expected to run on
refs_requiredstring[][]Commit types that require a footer reference

Default types: feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert.

Versioning schemes:

  • semver — BREAKING CHANGE or ! → major, feat → minor, everything else → patch. Resets lower components (e.g. 1.2.3 → 1.3.0). Supports --prerelease.
  • calver — date-based, ignores commit types. Uses calver_format (default YYYY.MM.PATCH). Patch increments within the same period, resets on period change. No --prerelease.
  • patch — always increments patch only, never touches major/minor. Breaking changes rejected unless --force is used. Intended for maintenance/LTS branches.

Scopes behavior:

  • Not set (default) — no scope validation, any scope accepted
  • scopes = "auto" — discover scopes from workspace layout (crates/*, packages/*, modules/*)
  • scopes = ["auth", "api"] — explicit allowlist

When scopes is set (either "auto" or an array) and --strict is used, a scope is required and must be in the resolved list. For git std commit, the resolved scopes populate the interactive scope prompt.

With scopes = "auto", if staged changes touch a top-level directory that doesn’t match any discovered scope (e.g. a new folder outside crates/, packages/, modules/), both git std --context and the interactive git std commit scope prompt surface a hint — the prompt offers an “other” choice to type the new scope directly, and .git-std.toml can be updated to add it permanently.

release_branch: When set, bumping on a different branch triggers a confirmation prompt (or an error in non-interactive mode unless --yes is supplied). When unset, both main and master are accepted without prompting.

refs_required: Types listed here must include a footer reference (e.g. Refs: #123). Validated during git std lint with --strict.

[versioning]

FieldTypeDefaultDescription
tag_prefixstring"v"Git tag prefix (e.g., v1.0.0)
prerelease_tagstring"rc"Default pre-release identifier
calver_formatstring"YYYY.MM.PATCH"Calendar version format (only when scheme = "calver")
tag_templatestring"{name}@{version}"Per-package tag format (only when monorepo = true)

Calendar version format tokens:

TokenDescriptionExample
YYYYFull year2026
YYShort year26
0MZero-padded month03
MMMonth (no padding)3
WWISO week number11
DDDay of month13
PATCHAuto-incrementing patch counter, resets each period0, 1, 2
DPDay of week (1=Mon–7=Sun) concatenated with patch counter30, 31, 32

Common formats: YYYY.MM.PATCH (monthly releases), YYYY.0M.PATCH (zero-padded month), YY.WW.DP (weekly with day-of-week), YYYY.MM.DD.PATCH (daily releases).

Bump rules are inferred from the scheme — not configurable. For semver: BREAKING CHANGE or ! triggers major, feat triggers minor, everything else triggers patch.

[changelog]

FieldTypeDefaultDescription
titlestring(none)Custom changelog title
hiddenstring[]["chore", "ci", "build", "style", "test"]Types excluded from changelog
bug_urlstring(none)URL template for bug/issue links

[changelog.sections]

Maps commit types to changelog section headings. Types not listed here use the type name as the heading.

KeyDefault
feat"Features"
fix"Bug Fixes"
perf"Performance"
refactor"Refactoring"
docs"Documentation"

[[version_files]]

Optional array of custom version files to update during bump. Each entry specifies a file path and a regex whose first capture group contains the version string.

[[version_files]]
path = "pom.xml"
regex = '<version>([^<]+)</version>'

[[version_files]]
path = "Chart.yaml"
regex = 'version:\s*(.+)'

path also accepts a glob pattern (containing any of * ? [ {), which expands to every matching file and applies the same regex to each one. This is useful for projects with one version-bearing file per item, such as a content registry with a metadata.version field in every skill file:

[[version_files]]
path = "skills/**/*.md"
regex = 'version:\s*(\S+)'

A glob that matches zero files emits a warning (no files matched version_files glob: <pattern>) but does not fail the bump. A literal path (no glob metacharacters) behaves exactly as before.

FieldTypeDescription
pathstringFile path or glob pattern, relative to repo root
regexstringRegex with capture group containing version

Entries with a missing (non-glob) path or missing regex are silently skipped. These are in addition to auto-detected version files (e.g. Cargo.toml).

[[packages]]

Explicit package definitions for monorepo workspaces. When monorepo = true and no packages are listed, git-std auto-discovers packages from workspace manifests (Cargo, npm, Deno) or subdirectories with version files.

[[packages]]
name = "core"
path = "crates/core"
scheme = "patch"                   # optional: override global scheme

[[packages.version_files]]         # optional: override version files
path = "version.txt"
regex = '(\d+\.\d+\.\d+)'

[packages.changelog]               # optional: override changelog config
title = "Core Changelog"
hidden = ["chore"]
FieldTypeDescription
namestringPackage name (used in tags and changelogs)
pathstringPackage root relative to repo root
schemestringOptional versioning scheme override
version_filesarrayOptional version files override
changelogtableOptional changelog config override

Entries with missing name or path are silently skipped.

Inferred settings

These are not configurable — git-std resolves them automatically:

ConcernResolution
Bump rulesInferred from scheme
Version filesAuto-detected (Cargo.toml)
URLsInferred from git remote get-url origin
Changelog outputCHANGELOG.md at root; {path}/CHANGELOG.md per package
Release commitchore(release): <version> (includes packages)
Package dependenciesResolved from workspace manifests (runtime only)

Minimal examples

No config needed — git-std works with zero configuration using conventional defaults.

Types and scopes only:

types = ["feat", "fix", "chore"]
scopes = ["auth", "api"]

Calver project:

scheme = "calver"

[versioning]
calver_format = "YYYY.0M.PATCH"

Custom changelog sections:

[changelog]
hidden = ["chore", "ci"]

[changelog.sections]
feat = "New Features"
fix = "Bug Fixes"
perf = "Performance Improvements"

Monorepo with per-package versioning:

monorepo = true
scheme = "semver"
scopes = "auto"

[versioning]
tag_template = "{name}@{version}"

[[packages]]
name = "core"
path = "crates/core"

[[packages]]
name = "cli"
path = "crates/cli"

When monorepo = true, each package is bumped independently based on commits touching its path. Packages are auto-discovered from workspace manifests if [[packages]] is omitted.

Dependency cascade: if package A bumps and package B depends on A (runtime dependency in Cargo.toml or package.json), B receives at least a patch bump. Use -p to skip cascade.

Per-package changelogs: each bumped package gets a CHANGELOG.md in its root directory. The root CHANGELOG.md includes all commits.

Mixed versioning schemes:

monorepo = true
scheme = "semver"

[versioning]
tag_template = "{name}@{version}"
calver_format = "YYYY.0M.PATCH"

[[packages]]
name = "core"
path = "crates/core"

[[packages]]
name = "api"
path = "crates/api"
scheme = "calver"              # override: date-based versioning

Skills

Agent skills for Claude Code, OpenCode, and GitHub Copilot.

Skills are authored under skills/ — the upskill source-registry root — and generated into .claude/skills/ and .agents/skills/ via:

upskill add ./ --claude --opencode

(or just skills). Regenerate after any change to skills/ and commit the generated output alongside the SSOT change.

/std-commit

Author a conventional commit for staged changes.

Invoke with /std-commit in your agent.

The skill:

  1. Checks git std is installed — offers to install via ./bootstrap or the install script if not.
  2. Runs git std --context to read project config, valid types, scopes, and the staged diff.
  3. Proposes a git std commit --type X [--scope Y] --message Z command.
  4. For feat and fix commits, asks for a related issue number and pre-fills it from the branch name when available (e.g. feat/123-my-feature → #123).
  5. Requires your approval before running.

/std-bump

Prepare a release, finalize a merged release, or recover interrupted publication.

Invoke with /std-bump in your agent.

The skill:

  1. Reads repository policy, command availability, configuration and release state; unavailable tooling or unsafe checkout state produces a concrete blocker.
  2. Resolves package selection, release process and publication scope, reusing authorization already given in the session.
  3. Previews the bump or existing-release tag plan and asks only for decisions or approval that remain unresolved.
  4. Validates the generated or merged release revision before publication, then publishes only the selected refs atomically when authorized.
  5. Inspects actual refs on recovery and reports local changes, remote refs, validation and hosted publication as separate states.

Release management

See release workflows for the preferred combined commit-and-tag process and the supported prepare-then-tag process. Agents use std-bump for both release preparation and finalizing an already merged release.

API Reference

Machine consumers should use the versioned CLI contracts. Release consumers should follow the release-integrity checks.

git-std is built on five crates. The four library crates implement domain logic only — no CLI, no git operations, no terminal output.

CrateDescriptiondocs.rs
git-stdCLI binary — orchestrates I/O, git, configdocs.rs/git-std
standard-commitConventional commit parsing, lintingdocs.rs/standard-commit
standard-versionVersion bump (semver + calver), file detectiondocs.rs/standard-version
standard-changelogChangelog generation from conventional commitsdocs.rs/standard-changelog
standard-githooksHook file format parsing, shim generationdocs.rs/standard-githooks

git std tag

Tag an existing release commit without another bump. The explicit <commit> argument identifies a release reachable from the configured release branch.

OptionPurpose
--dry-runValidate the exact plan without creating refs
--branch <name>Override the release branch
--package <name>Select a released package; repeat for several
--signCreate signed annotated tags
--push <remote>Publish only the planned tags atomically
--format <text|json>Select human or versioned machine output

The command reads configuration and versions from the target commit and leaves HEAD, the index and working files unchanged. It reuses matching annotated tags, refuses conflicts, and reports partial or uncertain outcomes without rollback. With --push, it verifies remote branch reachability and exact remote tag objects.

See release workflows for preflight requirements, both release processes, retry behavior and limitations. See CLI contracts for structured results and exit semantics.

Existing-release tagging design

The command’s orchestration lives in cli/tag/mod.rs. It builds one plan, preflights local tags and, when requested, the remote, then creates or adopts missing refs and publishes. Dry-run stops after preflight. Output is produced from the accumulated plan even on runtime failure, so callers can inspect partial completion.

plan.rs pins the commit and branch, selects release entries and derives tag names. identity.rs parses release subjects without Git access. snapshot.rs materializes selected blobs in a tempfile directory rather than checking out the target or registering a worktree. configuration.rs validates configuration types before the tolerant shared loader is used. manifests.rs checks structural TOML/JSON version fields, and versions.rs reuses standard-version readers and validates custom captures and Cargo inheritance. This keeps Git and terminal operations in the binary crate.

tags.rs validates annotations and signatures, preserves satisfied objects and uses create-only ref operations. remote.rs resolves one endpoint, observes branch ancestry, adopts remote objects, pushes pinned object IDs and checks publication. Git subprocess reads use git/release_refs.rs, which disables lazy fetching and replacement-object interpretation. Publishing the validated object ID protects the planned target when a local tag ref moves during a pre-push hook.

A dedicated tag command keeps existing-release validation separate from bump’s file updates and commit creation. The considered alternatives were a bump --tag-only mode, whose name would suggest a bump, and manual Git tagging, which leaves target validation and recovery to each caller. Agent guidance stays in std-bump so release preparation and finalization share one routing point. The combined bump/tag process remains preferred where branch policy permits it; post-merge tagging supports explicit user preference and required release PRs.

The binary acceptance cases are in spec/tests/tag.rs. The focused tag_* integration tests under crates/git-std/tests/ cover historical snapshots, remote-only adoption, partial completion, rejected atomic pushes and concurrent ref changes. Agent scenario fixtures and judges live in tests/skills/std-bump/, outside the installed skill: ancillary files within a skill directory are copied by upskill. Scenario harness checks and binary tests do not establish cross-client skill qualification; qualification requires the separate client transcripts and final-state judgments.

Release workflows

Prefer creating the release commit and annotated tag together on the configured release branch. Git-std also supports preparing a release first and tagging it later, for repositories that require release PRs or teams that prefer two steps. Both processes leave the tag pointing to the intended release commit in the release branch’s history.

Before releasing

Read .git-std.toml, repository instructions and hosting rules. Discover the release branch and its remote; do not assume main and origin. Fetch current remote state, preserve local work, and require a clean, synchronized release branch before creating a new release. Stop on divergence rather than discarding commits or force-pushing. In a worktree, avoid switching a branch owned by another checkout.

Run git std bump --dry-run with the intended package and version options. Review the version, changed files and changelog. Confirm unresolved release and publication decisions; an agent should reuse authorization already given in the session. Promoting 0.x to 1.0 requires an explicit stability decision and --first-major-release. A prerequisite error is not permission to bypass policy.

The examples below use main, origin and 1.2.3. Substitute the discovered branch, remote and exact planned tags. Run the repository’s validation command on the generated release revision before publishing it. A successful check on the revision before the bump does not validate the changed release files.

Preferred: create the commit and tag together

Normal development changes arrive through reviewed PRs. Where release commits may be pushed directly, create the bump commit and tag on the release branch:

git switch main
git fetch origin
git merge --ff-only origin/main
git std bump --dry-run
git std bump
just verify
git push --atomic --no-follow-tags --recurse-submodules=no origin \
  refs/heads/main:refs/heads/main refs/tags/v1.2.3:refs/tags/v1.2.3

just verify is an example: use the project’s prescribed validation command. Check synchronization in both directions before bumping; merge --ff-only alone does not detect local commits ahead of the remote. For multiple package tags, include each planned tag as an explicit refspec in the same atomic push.

An atomic push prevents a rejected branch update from leaving a published tag whose release commit did not reach main. If the server lacks atomic support, stop and resolve the publication process; do not retry non-atomically. Check that the remote has one identical effective fetch/push URL before using this recipe.

git std bump --push and git push --follow-tags remain supported, but do not guarantee atomic branch/tag publication. The agent skill uses the explicit atomic sequence so checks run after the bump and only the selected refs are sent.

Supported alternative: prepare, then tag

Prepare version files, changelog and the release commit without a tag:

git switch -c release/1.2.3 origin/main
git std bump --dry-run --no-tag
git std bump --no-tag --yes
just verify
git push origin HEAD:refs/heads/release/1.2.3

Here --yes acknowledges the deliberate preparation on a non-release branch; it does not grant hosting-policy exceptions. --no-tag --push skips pushing, so push the preparation branch explicitly. Open the release PR with the generated chore(release): 1.2.3 subject as its title. Preserve that identity when merging. For package releases, preserve the complete generated package/version list.

If the PR is pending, stop with the preparation branch, PR and validation results recorded. When it merges, obtain the resulting release commit ID from the forge and fetch it. Squash and rebase merges can rewrite the original commit; a tag created beforehand does not follow the new commit. Never infer the target solely from the current tip of main or an ambiguous search for a release subject.

Validate the resulting release revision. If main has advanced, use an isolated checkout of the exact release commit for validation. Then:

git fetch origin
git std tag <merged-release-commit> --push origin --dry-run
git std tag <merged-release-commit> --push origin

git std tag reads release identity, versions and tag configuration from that commit. It creates no new release commit, changes no version or changelog, and runs no bump lifecycle hooks. With --push, the observed remote release branch is authoritative; a stale or absent local main does not block a valid merged release. Only the selected tags are pushed atomically, never the branch. For local-only tagging, omit --push and ensure the target is reachable from the local release branch.

Existing-release tagging reference

git std tag <commit> [--dry-run] [--branch <name>]
                    [--package <name>]... [--sign]
                    [--push <remote>] [--format text|json]
  • <commit> is required and pinned to its full object ID. It must identify a chore(release) commit, optionally with a GitHub squash suffix such as (#123).
  • --branch selects a maintenance/release branch. Otherwise the target commit’s release_branch applies, then main/master fallback in the local or remote namespace being checked.
  • --package is repeatable and selects released packages in a monorepo; root tags are omitted when selecting packages. Without it, all entries in the release subject are tagged, not every package in the workspace.
  • --sign creates signed tags. Existing signatures are inspected and their trust-verification results reported separately; signature presence is not a verified signer-trust claim.
  • --push requires a configured remote name with one identical effective fetch and push URL. Mirror remotes, shallow repositories and partial clones are refused. Required Git capabilities are checked before work.
  • --dry-run --push reads remote state and may fetch objects, but changes no refs, working files, index or FETCH_HEAD.
  • --format json reports the target, branch, tag states, actions and diagnostics. Exit 0 means the requested work is satisfied, 1 a policy/input-state refusal, and 2 an operational failure or partial/uncertain completion.

Verify and recover

After publication, verify the remote tag object and that its peeled commit is reachable from the remote release branch. Report local bump, pushed refs, release CI, GitHub Release creation and package publication as separate states. A pushed tag is not proof that CI or a registry publication succeeded.

On interruption, inspect local and remote refs before doing anything else. Rerun git std tag with the same commit to finish missing tags or confirm a push whose response was lost. Matching annotated tags are preserved. A lightweight tag, different target, different annotation or distinct local/remote tag object is a conflict, even when two tag objects peel to the same commit. Inspect and resolve that conflict deliberately; the command never deletes or overwrites it.

If a signing operation or pre-push hook fails, some local tags may already exist. The error reports known state; no destructive rollback occurs. Do not repeat the bump to recover a tag push. Never move an already published protected version tag: fix forward with a new release. These workflows do not change hosting rulesets or disable repository validation.