Git Workflow
Overview
Git is the record of your project's evolution. Every commit should be atomic, meaningful, and reversible.
Core principle: Clean history enables clean debugging. Every commit tells a story.
The Iron Law
NO COMMIT WITHOUT PASSING TESTS. NO MERGE WITHOUT REVIEW.
When to Use
- Starting any new work (branch creation)
- Every completed task (commit)
- Finishing a feature (merge/PR)
- Dealing with conflicts
- Managing multiple parallel efforts
When NOT to Use
- Deciding what to build (use
brainstorming)
- Deciding how to build it (use
writing-plans)
- This is a reference skill for git operations, not a decision-making skill
Anti-Shortcut Rules
YOU CANNOT:
- Commit directly to main — always use feature branches
- Use git add . without reviewing staged files — stage interactively (git add -p)
- Force push to shared branches — only force push YOUR branches
- Commit with "WIP", "fix", or "update" messages — describe WHAT and WHY
- Commit debug code, console.logs, or TODO comments — clean up first
- Squash without reading the individual commits — understand what you're merging
- Skip tests before committing — failing tests = broken commit
- Resolve conflicts by picking one side without understanding both — merge INTENT
Common Rationalizations (Don't Accept These)
| Rationalization | Reality |
|---|
| "I'll clean up the history later" | You won't. Write clean commits now. |
| "It's just a small commit to main" | Small direct commits cause most merge conflicts and regressions. |
| "WIP commit, I'll squash later" | WIP commits become permanent. Write a real message. |
| "Force push is fine, nobody else uses this branch" | Until someone does. Only force push branches YOU own. |
| "I'll review what I staged before pushing" | Review before staging. After is too late — you'll miss things. |
| "The tests passed earlier" | Earlier ≠ now. Run them before every commit. |
Iron Questions
1. Does this commit compile and pass tests on its own?
2. If I revert this single commit, does the codebase still work?
3. Does the commit message explain WHY, not just WHAT?
4. Is this exactly ONE logical change? (not two changes in one commit)
5. Have I staged only the files related to this change?
6. Is there any debug code, commented-out code, or TODOs in the staged changes?
7. Would a reviewer understand this commit without additional context?
8. Am I committing to the correct branch?
Branch Strategy
Branch Types
| Branch | Pattern | Purpose | Lifetime |
|---|
main | main | Production code | Permanent |
| Feature | feat/<description> | New functionality | Until merged |
| Fix | fix/<description> | Bug fixes | Until merged |
| Refactor | refactor/<description> | Code improvements | Until merged |
| Experiment | experiment/<description> | Throw-away exploration | Until discarded |
Branch Lifecycle
1. CREATE branch from latest main
git checkout main && git pull
git checkout -b feat/description
2. WORK in small, committed increments
[write test → implement → verify → commit]
3. KEEP branch up to date (rebase on main regularly)
git fetch origin
git rebase origin/main
4. REVIEW before merge (code-review skill)
5. MERGE via PR (squash for feature branches, merge for long-lived)
6. DELETE branch after merge
git checkout main && git pull
git branch -d feat/description
Commit Convention
Format
<type>(<scope>): <description>
[optional body — explains WHY, not WHAT]
[optional footer — references issues, breaking changes]
Types
| Type | When |
|---|
feat | New feature |
fix | Bug fix |
refactor | Code change that neither fixes a bug nor adds a feature |
test | Adding or correcting tests |
docs | Documentation only |
style | Formatting, semicolons, etc. (no code change) |
chore | Build process, dependencies, tooling |
perf | Performance improvement |
ci | CI/CD changes |
Commit Quality
| ✅ Good Commit | ❌ Bad Commit |
|---|
feat(auth): add email validation with regex pattern | update stuff |
fix(api): prevent null reference in user lookup | fix bug |
test(cart): add edge cases for empty cart checkout | add tests |
refactor(db): extract query builder to shared util | refactor |
fix(payment): handle timeout when gateway returns 504 | wip |
Atomic Commits
Each commit should:
- Compile and pass tests on its own
- Be independently revertable
- Contain exactly ONE logical change
- Have a message that explains WHY, not just WHAT
Working with Conflicts
1. UNDERSTAND both sides of the conflict — read the diff carefully
2. IDENTIFY the intent of each change — what was each trying to accomplish?
3. MERGE intent, not text — the correct resolution may be different from both sides
4. VERIFY the merged result compiles and tests pass
5. IF unsure → ask the human partner (never guess on conflict resolution)
Stashing and Context Switching
# Save current work with descriptive message
git stash push -m "description of work in progress"
# Switch to urgent fix
git checkout -b fix/urgent-issue
# ... fix, test, and commit ...
# Return to original work
git checkout original-branch
git stash pop
Quick Reference
# Start new work
git checkout main && git pull
git checkout -b feat/description
# Save progress (interactive staging)
git add -p # Stage interactively
git diff --staged # Review staged changes
git commit -m "feat: description"
# Stay current
git fetch origin
git rebase origin/main
# Ready to merge
git push -u origin feat/description
# Create PR, get review, merge
# After merge
git checkout main && git pull
git branch -d feat/description
Red Flags — STOP
- Committing directly to main
- Giant commits with multiple unrelated changes
git add . without reviewing what's staged- Force pushing to shared branches
- Committing without running tests
- Vague commit messages ("fix", "update", "wip")
- Committing debug code, console.logs, or TODOs
- Resolving conflicts by always picking one side
- Not pulling main before creating a branch
Integration
- Branch creation: At start of
brainstorming or executing-plans
- Commits: After each
executing-plans task
- Merge: After
code-review approval
- Conflict resolution: During
refactoring-safely
- Before commit:
verification-before-completion
