Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

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.