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.tomlwith sensible defaults, inspectable viaconfig 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
| Flag | Description |
|---|---|
--help / -h | Print help |
--version / -V | Print version |
--color <when> | auto (default), always, never |
--completions <shell> | Generate shell completions to stdout |
--update | Update 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:
| Flag | Description |
|---|---|
--file <path> | Read message from file |
--range <range> | Validate all commits in a git revision range |
--strict | Enforce 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:
| Flag | Description |
|---|---|
--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 / -s | Add Signed-off-by trailer |
--dry-run | Print message without committing |
--amend | Pass --amend to git commit |
--sign / -S | GPG-sign the commit |
--all / -a | Stage 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:
| Flag | Description |
|---|---|
--dry-run | Print 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-release | Initial changelog, no bump |
--first-major-release | Confirm an intentional 0.x → 1.0 promotion (required whenever a bump would cross that boundary) |
--no-tag | Skip tag creation |
--no-commit | Update files only |
--sign / -S | GPG-sign commit and tag |
--skip-changelog | Bump without changelog |
--force | Allow breaking changes in patch-only scheme |
--stable [branch] | Create a stable branch for patch-only releases |
--minor | Use 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 / -y | Skip 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:
| Flag | Description |
|---|---|
--full | Regenerate 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:
- Creates
.githooks/directory. - Sets
core.hooksPathto.githooks. - Writes
.hookstemplates (pre-commit,commit-msg,pre-push, etc.). - Prompts which hooks to enable, writes shims.
- Generates
./bootstrapscript. - Generates
.githooks/bootstrap.hooks. - Creates
.git-std.tomlwith taplo schema directive (if absent). - Appends post-clone section to
README.mdandAGENTS.md(if found). - 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:
| Flag | Description |
|---|---|
--force | Overwrite existing files |
--refresh | Merge 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:
| Subcommand | Description |
|---|---|
run <hook> | Execute a hook manually |
list | Display 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):
| Flag | Description |
|---|---|
--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 file | Action |
|---|---|
.githooks/ | git config core.hooksPath .githooks |
.gitattributes | Local LFS filters + git lfs pull (if filter=lfs) |
.git-blame-ignore-revs | git 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:
| Flag | Description |
|---|---|
--dry-run | Print 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:
| Section | Contents |
|---|---|
Status | Tool versions: git, git-lfs (if .gitattributes needs it), git-std with update notice if available |
Hooks | All .githooks/*.hooks files with commands and sigils (! required, ? advisory), enabled/disabled state |
Configuration | All .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:
| Flag | Description |
|---|---|
--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:
| Flag | Description |
|---|---|
--describe | Cargo-style describe: -dev.N pre-release + +hash[.dirty] metadata |
--next | Next version from conventional commits since the last tag |
--label | Bump label (major/minor/patch/none), accounting for pre-1.0 |
--code | Integer 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.
| Option | Purpose |
|---|---|
--dry-run | Validate the exact plan without creating refs |
--branch <name> | Override the release branch |
--package <name> | Select a released package; repeat for several |
--sign | Create 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
| Command | Contract | Example |
|---|---|---|
git std version --format json | schemas/v1/cli/version.schema.json | schemas/v1/cli/examples/version.json |
git std bump --dry-run --format json | schemas/v1/cli/bump.schema.json | schemas/v1/cli/examples/bump.json |
git std lint --format json | schemas/v1/cli/lint.schema.json | schemas/v1/cli/examples/lint.json |
git std lint --format sarif | SARIF 2.1.0 | Registered codes are ruleId values with matching driver rule descriptors. |
git std hook list --format json | schemas/v1/cli/hook-list.schema.json | schemas/v1/cli/examples/hook-list.json |
git std hook run <hook> --format json | schemas/v1/cli/hook-run.schema.json | schemas/v1/cli/examples/hook-run.json |
git std doctor --format json | schemas/v1/cli/doctor.schema.json | schemas/v1/cli/examples/doctor.json |
git std registry --format json | schemas/v1/cli/registry.schema.json | schemas/v1/cli/examples/registry.json |
git std tag <commit> --format json | schemas/v1/cli/tag.schema.json | schemas/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
| Platform | Target |
|---|---|
| Linux x86-64 | x86_64-unknown-linux-musl |
| Linux ARM64 | aarch64-unknown-linux-musl |
| macOS x86-64 | x86_64-apple-darwin |
| macOS Apple Silicon | aarch64-apple-darwin |
| Windows x86-64 | x86_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:
- all five jobs cross-build successfully;
- OIDC keyless signing and transparency-log inclusion succeed;
- GitHub stores and verifies each provenance attestation;
- the GitHub Release exposes all 25 expected files without renaming; and
- 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 CHANGEor!suffix → majorfeat→ minorfix/perf/revert→ patchdocs/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:
| Format | Example | Use case |
|---|---|---|
YYYY.MM.PATCH | 2026.3.0 | Monthly releases |
YYYY.0M.PATCH | 2026.03.0 | Zero-padded |
YY.WW.DP | 26.12.30 | Weekly + day |
YYYY.MM.DD.PATCH | 2026.3.18.0 | Daily 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
| Hook | When it runs | Typical use |
|---|---|---|
pre-commit | Before a commit is created | Lint, format, run fast tests |
commit-msg | After the message is written | Validate conventional commit |
prepare-commit-msg | Before the editor opens | Pre-fill commit template |
post-commit | After the commit is created | Notifications, stats |
pre-push | Before push sends data to remote | Full test suite, build validation |
post-merge | After a merge completes | Reinstall deps, rebuild |
Command prefixes
Each .hooks file contains one command per line with a
prefix that controls behaviour:
| Prefix | Name | Behaviour |
|---|---|---|
! | check | Run command, block on failure |
~ | fix | Isolate staged files, run, re-stage |
? | advisory | Run 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
| Field | Type | Default | Description |
|---|---|---|---|
scheme | string | "semver" | Versioning scheme (see below) |
types | string[] | 11 standard types | Allowed conventional commit types |
scopes | "auto" or string[] | None | Scope discovery or explicit allowlist |
strict | bool | false | Enforce types/scopes validation without --strict flag |
monorepo | bool | false | Enable per-package versioning |
release_branch | string | (none) | Branch that git std bump is expected to run on |
refs_required | string[] | [] | Commit types that require a footer reference |
Default types: feat, fix, docs, style, refactor,
perf, test, chore, ci, build, revert.
Versioning schemes:
semver—BREAKING CHANGEor!→ 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. Usescalver_format(defaultYYYY.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--forceis 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]
| Field | Type | Default | Description |
|---|---|---|---|
tag_prefix | string | "v" | Git tag prefix (e.g., v1.0.0) |
prerelease_tag | string | "rc" | Default pre-release identifier |
calver_format | string | "YYYY.MM.PATCH" | Calendar version format (only when scheme = "calver") |
tag_template | string | "{name}@{version}" | Per-package tag format (only when monorepo = true) |
Calendar version format tokens:
| Token | Description | Example |
|---|---|---|
YYYY | Full year | 2026 |
YY | Short year | 26 |
0M | Zero-padded month | 03 |
MM | Month (no padding) | 3 |
WW | ISO week number | 11 |
DD | Day of month | 13 |
PATCH | Auto-incrementing patch counter, resets each period | 0, 1, 2 |
DP | Day of week (1=Mon–7=Sun) concatenated with patch counter | 30, 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]
| Field | Type | Default | Description |
|---|---|---|---|
title | string | (none) | Custom changelog title |
hidden | string[] | ["chore", "ci", "build", "style", "test"] | Types excluded from changelog |
bug_url | string | (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.
| Key | Default |
|---|---|
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.
| Field | Type | Description |
|---|---|---|
path | string | File path or glob pattern, relative to repo root |
regex | string | Regex 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"]
| Field | Type | Description |
|---|---|---|
name | string | Package name (used in tags and changelogs) |
path | string | Package root relative to repo root |
scheme | string | Optional versioning scheme override |
version_files | array | Optional version files override |
changelog | table | Optional changelog config override |
Entries with missing name or path are silently skipped.
Inferred settings
These are not configurable — git-std resolves them automatically:
| Concern | Resolution |
|---|---|
| Bump rules | Inferred from scheme |
| Version files | Auto-detected (Cargo.toml) |
| URLs | Inferred from git remote get-url origin |
| Changelog output | CHANGELOG.md at root; {path}/CHANGELOG.md per package |
| Release commit | chore(release): <version> (includes packages) |
| Package dependencies | Resolved 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:
- Checks
git stdis installed — offers to install via./bootstrapor the install script if not. - Runs
git std --contextto read project config, valid types, scopes, and the staged diff. - Proposes a
git std commit --type X [--scope Y] --message Zcommand. - For
featandfixcommits, asks for a related issue number and pre-fills it from the branch name when available (e.g.feat/123-my-feature→#123). - 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:
- Reads repository policy, command availability, configuration and release state; unavailable tooling or unsafe checkout state produces a concrete blocker.
- Resolves package selection, release process and publication scope, reusing authorization already given in the session.
- Previews the bump or existing-release tag plan and asks only for decisions or approval that remain unresolved.
- Validates the generated or merged release revision before publication, then publishes only the selected refs atomically when authorized.
- 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.
| Crate | Description | docs.rs |
|---|---|---|
| git-std | CLI binary — orchestrates I/O, git, config | docs.rs/git-std |
| standard-commit | Conventional commit parsing, linting | docs.rs/standard-commit |
| standard-version | Version bump (semver + calver), file detection | docs.rs/standard-version |
| standard-changelog | Changelog generation from conventional commits | docs.rs/standard-changelog |
| standard-githooks | Hook file format parsing, shim generation | docs.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.
| Option | Purpose |
|---|---|
--dry-run | Validate the exact plan without creating refs |
--branch <name> | Override the release branch |
--package <name> | Select a released package; repeat for several |
--sign | Create 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 achore(release)commit, optionally with a GitHub squash suffix such as(#123).--branchselects a maintenance/release branch. Otherwise the target commit’srelease_branchapplies, then main/master fallback in the local or remote namespace being checked.--packageis 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.--signcreates signed tags. Existing signatures are inspected and their trust-verification results reported separately; signature presence is not a verified signer-trust claim.--pushrequires 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 --pushreads remote state and may fetch objects, but changes no refs, working files, index or FETCH_HEAD.--format jsonreports 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.