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.