Branching & Merging

Rust teams typically use trunk-based flow on main with short feat/* branches, optional release/* trains for multi-crate workspaces, and rebase to keep history reviewable.

Recipe

git checkout main
git pull --rebase origin main
git checkout -b feat/billing-tax
# work, commit
git fetch origin
git rebase origin/main
git push -u origin feat/billing-tax
# open PR -> squash merge to main

When to reach for this:

• Starting any ticket work
• Preparing PR for review
• Coordinating API + worker + migration releases

Working Example

# Release train for workspace 2.6.0
git checkout -b release/2.6.0 origin/main
# only bugfixes cherry-picked
git tag v2.6.0
git push origin v2.6.0
 
# Hotfix from production tag
git checkout -b hotfix/2.5.1 v2.5.0
git cherry-pick <fix-sha>
git push origin hotfix/2.5.1

What this demonstrates:

• Feature branches branch from latest main
• Release branch stabilizes before tag
• Hotfix branches from production tag, not ahead-of-prod main

Deep Dive

Merge Strategies

Rust-Specific Coordination

When sqlx migrations and binary deploys must align, cut release/* and run full cargo test --all-features before tag.

Gotchas

• Long-lived feature branches - Cargo.lock conflicts multiply. Fix: rebase daily.
• Merging main into release/* - pulls unvetted features. Fix: cherry-pick fixes only.
• Rebase after PR approval - invalidates review SHA. Fix: rebase before final approval or merge queue.
• Force push main - audit nightmare. Fix: branch protection blocks force push.
• Binary + lib version skew - forgot to bump workspace crate. Fix: release checklist for all workspace members.

Alternatives

FAQs

Related

• Essential Git Commands
• Merge Conflict Resolution Checklist
• Release & versioning
• Git Best Practices

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+.