Git Best Practices

Twenty-five Git practices for Rust teams - clean history, reviewable commits, and CI-aligned hooks.

main is always integration truth: Every merged PR passes fmt, clippy, and test.
Commit Cargo.lock for applications: Reproducible cargo build --locked in CI.
Ticket IDs in every commit: feat(api): health route [API-42] for cherry-pick traceability.
Squash merge features when policy allows: One ticket, one commit on main.
Short-lived feature branches: Rebase main daily to avoid lockfile conflicts.
Cut release/x.y for coordinated trains: API + worker + migration ship together.
Release branch accepts bugfixes only during freeze windows.
Cherry-pick to release/*, never merge main into release/*.
Tag from release/* after staging sign-off: v2.6.0 triggers pipeline.
Merge release/* back to main after rollout and delete release branch.
Hotfix branches from production tags, not ahead-of-prod main.
Backport every hotfix to main and active release/*.
Never force-push shared branches: main, release/*, hotfix/*.
--force-with-lease only on private feat/* before review completes.
Pre-commit mirrors CI: cargo fmt, clippy -D warnings, fast cargo test.
Global gitignore target/ and .env - never commit secrets or build artifacts.
Use worktrees for PR review instead of stashing long builds.
gh pr create --fill after push - link CI checks in PR template.
Document conflict hotspots in PR when touching Cargo.toml workspace deps.
Sign commits when org requires SSH or GPG signing.
Protect main with required checks - fmt, clippy, test, locked build.
PR size discipline - split refactors from behavior changes.
Reflog awareness - recover deleted branches within retention window.
Tag binary releases matching container tags (v1.2.3).
CHANGELOG entry with release tag - link git compare URL in notes.

FAQs

Library crate: commit Cargo.lock?

Libraries often omit lock in repo; binaries and workspaces commit lock.

Monorepo one or many locks?

Single workspace root Cargo.lock is standard for Rust workspaces.

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.

Git Best Practices

Twenty-five Git practices for Rust teams - clean history, reviewable commits, and CI-aligned hooks.

main is always integration truth: Every merged PR passes fmt, clippy, and test.

Commit Cargo.lock for applications: Reproducible cargo build --locked in CI.

Ticket IDs in every commit: feat(api): health route [API-42] for cherry-pick traceability.

Squash merge features when policy allows: One ticket, one commit on main.

Short-lived feature branches: Rebase main daily to avoid lockfile conflicts.

Cut release/x.y for coordinated trains: API + worker + migration ship together.

Release branch accepts bugfixes only during freeze windows.

Cherry-pick to release/*, never merge main into release/*.

Tag from release/* after staging sign-off: v2.6.0 triggers pipeline.

Merge release/* back to main after rollout and delete release branch.

Hotfix branches from production tags, not ahead-of-prod main.

Backport every hotfix to main and active release/*.

Never force-push shared branches: main, release/*, hotfix/*.

--force-with-lease only on private feat/* before review completes.

Pre-commit mirrors CI: cargo fmt, clippy -D warnings, fast cargo test.

Global gitignore target/ and .env - never commit secrets or build artifacts.

Use worktrees for PR review instead of stashing long builds.

gh pr create --fill after push - link CI checks in PR template.

Document conflict hotspots in PR when touching Cargo.toml workspace deps.

Sign commits when org requires SSH or GPG signing.

Protect main with required checks - fmt, clippy, test, locked build.

PR size discipline - split refactors from behavior changes.

Reflog awareness - recover deleted branches within retention window.

Tag binary releases matching container tags (v1.2.3).

CHANGELOG entry with release tag - link git compare URL in notes.

Git Best Practices

FAQs

Related

Search Documentation

Git Best Practices

FAQs

Related