Development
Git Workflow and Versioning
Structures git workflow practices. Use when making any code change, committing, branching, resolving conflicts, or organizing work.
Structures git workflow practices. Use when making any code change, committing, branching, resolving conflicts, or organizing work.
Git is your safety net. Treat commits as save points, branches as sandboxes, and history as documentation.
Always. Every code change flows through git.
Keep main always deployable. Work in short-lived feature branches that merge back within 1-3 days.
main ──●──●──●──●──●──●──●──●──●── (always deployable)
╲ ╱ ╲ ╱
●──●─╱ ●──╱ ← short-lived feature branches (1-3 days)
Each successful increment gets its own commit.
Work pattern:
Implement slice → Test → Verify → Commit → Next slice
Not this:
Implement everything → Hope it works → Giant commit
Each commit does one logical thing:
# Good: Each commit is self-contained
git log --oneline
a1b2c3d Add task creation endpoint with validation
d4e5f6g Add task creation form component
h7i8j9k Connect form to API and add loading state
m1n2o3p Add task creation tests (unit + integration)
# Bad: Everything mixed together
x1y2z3a Add task feature, fix sidebar, update deps, refactor utils
Commit messages explain the why, not just the what:
# Good: Explains intent
feat: add email validation to registration endpoint
Prevents invalid email formats from reaching the database.
Uses Zod schema validation at the route handler level.
# Bad: Describes what's obvious from the diff
update auth.ts
Format:
<type>: <short description>
<optional body explaining why, not what>
Types:
feat — New featurefix — Bug fixrefactor — Code change that neither fixes a bug nor adds a featuretest — Adding or updating testsdocs — Documentation onlychore — Tooling, dependencies, configDon't combine formatting changes with behavior changes:
# Good: Separate concerns
git commit -m "refactor: extract validation logic to shared utility"
git commit -m "feat: add phone number validation to registration"
# Bad: Mixed concerns
git commit -m "refactor validation and add phone number field"
Target ~100 lines per commit/PR:
~100 lines → Easy to review, easy to revert
~300 lines → Acceptable for a single logical change
~1000 lines → Split into smaller changes
main (always deployable)
│
├── feature/task-creation ← One feature per branch
├── feature/user-settings ← Parallel work
└── fix/duplicate-tasks ← Bug fixes
feature/<short-description> → feature/task-creation
fix/<short-description> → fix/duplicate-tasks
chore/<short-description> → chore/update-deps
refactor/<short-description> → refactor/auth-module
Agent starts work
│
├── Makes a change
│ ├── Test passes? → Commit → Continue
│ └── Test fails? → Revert to last commit → Investigate
│
└── Feature complete → All commits form a clean history
Before every commit:
# 1. Check what you're about to commit
git diff --staged
# 2. Ensure no secrets
git diff --staged | grep -i "password\|secret\|api_key\|token"
# 3. Run tests
npm test
# 4. Run linting
npm run lint
# 5. Run type checking
npx tsc --noEmit
# Find which commit introduced a bug
git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>
# View what changed recently
git log --oneline -20
git diff HEAD~5..HEAD -- src/
# Find who last changed a specific line
git blame src/services/task.ts
# Search commit messages for a keyword
git log --grep="validation" --oneline
For every commit:
.gitignore covers standard exclusions