Recipes

Git aliases

Shorten common commands with git aliases:

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

Then use:

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

Semver workflow

Semver is the default scheme — no configuration needed.

Bump rules are inferred from conventional commits:

• BREAKING CHANGE or ! suffix → major
• feat → minor
• Everything else → patch

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

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:

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+"([^"]+)"'

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

Command prefixes

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

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

Managing hooks

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