# Feature branches (link to issue)
issue/<number>-<brief-description>
issue/123-add-user-auth

# When no issue exists
feature/<description>
fix/<description>
hotfix/<description>

[ ] Does ONE logical thing
[ ] Leaves codebase working (tests pass)
[ ] Message doesn't need "and" in title
[ ] Can be reverted independently
[ ] Title < 50 chars, body wraps at 72

# Stage changes hunk-by-hunk
git add -p

# Options:
# y - stage this hunk
# n - skip this hunk
# s - split into smaller hunks
# e - manually edit the hunk
# q - quit

# Review what's staged
git diff --staged    # What will be committed
git diff             # What won't be committed

# Separate concerns
git add -p && git commit -m "refactor: Extract database pool"
git add -p && git commit -m "feat(#456): Add query caching"

# Never combine unrelated changes
# BAD:  "feat: Add auth and fix formatting"
# GOOD: Two separate commits

# ALWAYS check reflog first - it has everything
git reflog

# Shows ALL recent HEAD movements
# Even "deleted" commits live here for 90 days

# Undo last commit, keep changes staged
git reset --soft HEAD~1

# Find lost commits
git reflog | grep "your message"

# Recover to previous state
git reset --hard HEAD@{1}

# Safe force push (feature branches only)
git push --force-with-lease

# 1. Start fresh
git checkout main && git pull origin main
git checkout -b issue/123-my-feature

# 2. Work with atomic commits
git add -p
git commit -m "feat(#123): Add User model"

# 3. Stay updated
git fetch origin && git rebase origin/main

# 4. Push and PR
git push -u origin issue/123-my-feature
gh pr create --fill

# 5. Cleanup after merge
git checkout main && git pull
git branch -d issue/123-my-feature

Avoid:
- Long-lived branches (> 1 week)
- Merging main into feature (use rebase)
- Direct commits to main
- Force push to shared branches
- Commits that need "and" in message
- Committing broken code

# 1. Create feature branch FROM main
git checkout main && git pull
git checkout -b issue/123-add-feature

# 2. Work on feature branch
git add -p && git commit -m "feat(#123): Add feature"

# 3. Push feature branch
git push -u origin issue/123-add-feature

# 4. Create PR targeting main (or dev)
gh pr create --base main

# 5. Merge via PR only (after review + CI)

# Issue-linked (preferred)
issue/<number>-<brief-description>
issue/123-add-user-auth

# Type-based (when no issue exists)
feature/<description>
fix/<description>
hotfix/<description>        # For urgent production fixes
docs/<description>
refactor/<description>
test/<description>
chore/<description>

# Create hotfix branch from main
git checkout main && git pull
git checkout -b hotfix/critical-fix

# Fix, test, push
git add . && git commit -m "fix: Resolve critical auth bypass"
git push -u origin hotfix/critical-fix

# Create PR with expedited review
gh pr create --base main --title "HOTFIX: Critical auth bypass"

# Bypasses code review and CI
git checkout main
git commit -m "quick fix"
git push origin main

# PR-based deployment
git checkout -b fix/issue-123
git commit -m "fix(#123): Resolve auth bug"
git push -u origin fix/issue-123
gh pr create --base main

# Squash WIP commits before pushing
git rebase -i HEAD~3

# In the editor:
pick abc1234 feat(#123): Add user validation
fixup def5678 WIP: more validation
fixup ghi9012 fix typo

# Result: One clean commit instead of three messy ones

# Initial commit
git commit -m "feat(#123): Add user model"

# Later fixes to the same work
git commit --fixup HEAD    # Auto-squash into previous
git commit --fixup HEAD~2  # Auto-squash into specific commit

# Before pushing, auto-squash all fixups
git rebase -i --autosquash HEAD~5

# BAD history
abc1234 WIP
def5678 stuff
ghi9012 fix
jkl3456 more fixes
mno7890 finally works

# GOOD history
abc1234 feat(#123): Add user validation with Zod schemas
def5678 test(#123): Add validation edge case tests
ghi9012 docs(#123): Document validation error codes

# Pushed without cleanup
abc1234 WIP
def5678 fix
ghi9012 more fixes
jkl3456 finally works

# Squashed before pushing
git rebase -i --autosquash HEAD~4
# Result: One clean commit
abc1234 feat(#123): Add user validation with edge case handling

# Keep feature branch up to date
git fetch origin
git rebase origin/main

# If conflicts arise
# 1. Resolve conflicts in each file
# 2. Stage resolved files
git add <resolved-files>
# 3. Continue rebase
git rebase --continue

# If rebase goes wrong
git rebase --abort  # Start over

DO NOT rebase if:
- Branch is shared with other developers (changes published history)
- You've already pushed and others have pulled
- Working on a release branch

USE merge instead:
git merge origin/main

# 1. Understand the conflict
git diff  # Shows conflict markers

# 2. Resolve by choosing correct code
# <<<<<<< HEAD       ← your changes
# ...
# =======
# ...                ← incoming changes
# >>>>>>> main

# 3. Test after resolution
npm test  # Verify nothing broke

# 4. Continue
git add <resolved-files>
git rebase --continue

# SAFE: Force push your own feature branch
git push --force-with-lease origin issue/123-feature

# DANGEROUS: Never force push protected branches
git push --force origin main  # NEVER DO THIS

# --force-with-lease prevents overwriting others' pushes
# It fails if remote has commits you don't have locally

# Creates noisy merge commits
git checkout feature-branch
git merge origin/main  # Creates "Merge branch 'main' into feature" commit

# Linear history
git checkout feature-branch
git rebase origin/main  # Replays feature commits on top of main
git push --force-with-lease

# WRONG: Claude Code only sees root, misses service-specific patterns
claude  # From monorepo root — no service context

# Start Claude Code with additional service context
claude --add-dir ../shared
claude --add-dir ../shared --add-dir ../web

# Enable CLAUDE.md loading from added directories
export CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1

monorepo/
  CLAUDE.md               # Root: workspace-wide rules
  packages/
    api/
      CLAUDE.md           # API: FastAPI patterns, test commands
      package.json
    web/
      CLAUDE.md           # Web: Next.js patterns, component library
      package.json
    shared/
      CLAUDE.md           # Shared: library API, versioning rules
      package.json

# Monorepo Root

## Conventions
- Commit format: conventional commits
- Branch naming: issue/<number>-<desc>
- CI: Turborepo pipeline, affected-only builds

## Cross-Service Rules
- Shared types live in packages/shared
- API changes require web compatibility check

# API Service

## Stack
- FastAPI 0.115+, Python 3.12+
- SQLAlchemy 2.x async

## Test Commands
npm run test:api       # Unit tests
npm run test:api:e2e   # Integration tests

## Patterns
- All endpoints return RFC 9457 errors
- Use dependency injection via FastAPI Depends()

git reset --hard HEAD~3  # "Oh no, those commits are lost forever\!"
# Wrong — reflog still has them

# View all recent HEAD movements
git reflog --date=relative

# Find lost commits by message
git reflog | grep "search-term"

# Show reflog for specific branch
git reflog show branch-name

# Once found (e.g., abc1234), recover:
git branch recovered-work abc1234
# Or cherry-pick specific commits:
git cherry-pick abc1234

# Find the branch last commit
git reflog | grep -i "branch-name"
# Or check all recent activity:
git reflog --all | head -30

# Recreate the branch at that commit
git checkout -b recovered-branch abc1234

# Verify
git log --oneline -5

# Find the pre-rebase state in reflog
git reflog | head -20
# Look for: "rebase (start): checkout main"
# The entry BEFORE that is your pre-rebase state

# Alternative: ORIG_HEAD is set before rebase
git reset --hard ORIG_HEAD

# WARNING: ORIG_HEAD is overwritten by other operations
# Use reflog if ORIG_HEAD might be stale

git reset --hard HEAD~1  # Changes gone, no backup reference saved
# If this was wrong, recovery requires digging through reflog

# Save backup before destructive operation
BACKUP_REF=$(git rev-parse HEAD)
echo "Backup ref: $BACKUP_REF"

# Show what will be lost
git show HEAD --stat

# Then execute
git reset --hard HEAD~1

# Recovery if needed:
git reset --hard $BACKUP_REF

git reset --soft HEAD~1
git status  # Changes are still staged

# Show changes to file first
git diff path/to/file

# Restore using modern git (2.23+)
git restore path/to/file

# Or older syntax
git checkout HEAD -- path/to/file

# Modern syntax
git restore --staged path/to/file

# Older syntax
git reset HEAD path/to/file

git stash        # Generic "WIP on main" message
git stash        # Another generic stash
git stash pop    # Which one was it? Wrong one applied
git stash drop   # Lost the other one

# Save with descriptive name
git stash push -m "auth-flow: halfway through token refresh"

# List stashes to find the right one
git stash list
# stash@{0}: On main: auth-flow: halfway through token refresh
# stash@{1}: On main: fix: database connection pooling

# Apply specific stash (keeps it in stash list)
git stash apply stash@{1}

# Apply and remove from list
git stash pop stash@{0}

# Stash entries appear in reflog briefly
git fsck --no-reflog | grep commit

# Once found, apply it:
git stash apply <commit-hash>

# Stash only specific files
git stash push -m "partial work" -- path/to/file1 path/to/file2

# Stash including untracked files
git stash push -u -m "including new files"

# WRONG: Merge commits pollute history
git checkout feature/auth-service
git merge main  # Creates unnecessary merge commit
git merge feature/auth-base  # More merge commits
# History becomes unreadable mess

# When base PR (auth-base) gets review feedback:
git checkout feature/auth-base
git add -p && git commit -m "fix: Address review feedback"
git push

# Rebase dependent branches in order:
git checkout feature/auth-service
git rebase feature/auth-base
git push --force-with-lease  # Safe: won't overwrite others' work

git checkout feature/auth-ui
git rebase feature/auth-service
git push --force-with-lease

# PR #1 merged to main
git checkout main && git pull origin main

# Retarget PR #2 to main (via GitHub CLI)
gh pr edit 102 --base main

# Rebase PR #2 on updated main
git checkout feature/auth-service
git rebase main
git push --force-with-lease

# After PR #2 merges, repeat for PR #3

#!/bin/bash
# stack-rebase.sh — Rebase entire stack in sequence
STACK=(
  "feature/auth-base"
  "feature/auth-service"
  "feature/auth-ui"
)

BASE="main"
for branch in "${STACK[@]}"; do
  echo "Rebasing $branch onto $BASE..."
  git checkout "$branch"
  git rebase "$BASE" || { echo "Conflict in $branch! Resolve and re-run."; exit 1; }
  git push --force-with-lease
  BASE="$branch"
done
echo "Stack rebased successfully!"

# WRONG: One 1500-line PR that takes days to review
git checkout -b feature/auth
# ... 3 days of work, 40 files changed ...
gh pr create --title "feat: Add complete auth system"
# Reviewer: "This is too large to review effectively"

# PR 1: User model (base) — targets main
git checkout main && git pull origin main
git checkout -b feature/auth-base
git add -p && git commit -m "feat(#100): Add User model"
git push -u origin feature/auth-base
gh pr create --base main --title "feat(#100): Add User model [1/3]" \
  --body "## Stack
- **PR 1/3: User model (this PR)**
- PR 2/3: Auth service (depends on this)
- PR 3/3: Login UI (depends on #2)

## Changes
- Add User model with validation
- Add database migrations"

# PR 2: Auth service — targets PR 1's branch
git checkout -b feature/auth-service  # branches from auth-base
git add -p && git commit -m "feat(#100): Add auth service"
git push -u origin feature/auth-service
gh pr create --base feature/auth-base \
  --title "feat(#100): Add auth service [2/3]" \
  --body "**Depends on #101** — merge that first"

# PR 3: Login UI — targets PR 2's branch
git checkout -b feature/auth-ui
git commit -m "feat(#100): Add login form"
git push -u origin feature/auth-ui
gh pr create --base feature/auth-service \
  --title "feat(#100): Add login UI [3/3]"

## PR Stack for Auth Feature (#100)

| Order | PR | Status | Branch |
|-------|-----|--------|--------|
| 1 | #101 | Merged | feature/auth-base |
| 2 | #102 | Review | feature/auth-service |
| 3 | #103 | Draft | feature/auth-ui |

**Merge order**: #101 -> #102 -> #103

main ─────●───────●───────●───────●───────●──────
           \     / \     / \     / \     /
            ●───●   ●───●   ●───●   ●───●
           issue/  fix/    feat/   hotfix/
           123     456     789     critical

           1-2     0.5     2-3     0.5
           days    days    days    days

git checkout main
git pull origin main
git checkout -b issue/123-my-task

# Make changes, commit atomically
git add -p
git commit -m "feat(#123): Part 1"

# Stay updated with main
git fetch origin
git rebase origin/main

# Push and create PR
git push -u origin issue/123-my-task
gh pr create --fill

git checkout main
git pull origin main
git branch -d issue/123-my-task

# Create release branch only when needed
git checkout -b release/v1.2 main
# Cherry-pick specific fixes
git cherry-pick abc1234

// Merge incomplete work behind flag
if (process.env.FF_NEW_FEATURE) {
  return <NewFeature />;
}
return <CurrentFeature />;

git add -p              # Stage all modified files interactively
git add -p file.ts      # Stage specific file interactively

$ git add -p

diff --git a/src/auth.ts b/src/auth.ts
@@ -10,6 +10,10 @@ export function login(user: string) {
+  // Validate input
+  if (!user) throw new Error('User required');
+
   const token = generateToken(user);
+  logAudit('login', user);  // Added for audit
   return token;
 }

Stage this hunk [y,n,q,a,d,s,e,?]? s  # Split it!

# Now shows smaller hunks...
@@ -10,6 +10,8 @@
+  // Validate input
+  if (!user) throw new Error('User required');

Stage this hunk? y  # Stage validation

@@ -14,6 +16,7 @@
+  logAudit('login', user);  # Added for audit

Stage this hunk? n  # Skip audit (different commit)

Stage this hunk? e

# Opens editor with:
# -context line
# +added line
# +another added line

# Delete lines you DON'T want staged
# Keep lines you DO want staged
# Save and exit

# What will be committed
git diff --staged

# What won't be committed
git diff

# Summary
git status

What happened?
│
├─ Committed to wrong branch?
│  ├─ Not pushed → cherry-pick + reset
│  └─ Pushed → cherry-pick + revert
│
├─ Need to undo commit?
│  ├─ Keep changes → git reset --soft HEAD~1
│  ├─ Discard changes → git reset --hard HEAD~1
│  └─ Already pushed → git revert HEAD
│
├─ Lost commits?
│  └─ Check reflog → git reset --hard HEAD@{N}
│
├─ Deleted branch?
│  └─ Check reflog → git checkout -b name SHA
│
├─ Bad merge?
│  ├─ Not pushed → git reset --hard HEAD~1
│  └─ Pushed → git revert -m 1 SHA
│
└─ Rebase disaster?
   ├─ Still rebasing → git rebase --abort
   └─ Completed → reflog → reset

# Keep changes staged
git reset --soft HEAD~1

# Keep changes unstaged
git reset --mixed HEAD~1

# Discard changes completely (DANGER)
git reset --hard HEAD~1

# Already pushed - create reverting commit
git revert HEAD

# Note the commit SHA
git log -1  # abc1234

# Undo on wrong branch
git reset --hard HEAD~1

# Apply to correct branch
git checkout correct-branch
git cherry-pick abc1234

# Cherry-pick to correct branch
git checkout correct-branch
git cherry-pick abc1234
git push origin correct-branch

# Revert on wrong branch
git checkout wrong-branch
git revert abc1234
git push origin wrong-branch

# Find in reflog
git reflog

# Reset to before the bad operation
git reset --hard HEAD@{N}

# Or cherry-pick specific commits
git cherry-pick abc1234

# Find branch's last commit
git reflog | grep "checkout: moving from deleted-branch"

# Recreate branch
git checkout -b recovered-branch abc1234

# Abort and start over
git rebase --abort

# Skip problematic commit
git rebase --skip

# Continue after fixing conflicts
git add .
git rebase --continue

# Find pre-rebase state in reflog
git reflog

# Reset to before rebase
git reset --hard HEAD@{N}

# Force push if needed (feature branches only!)
git push --force-with-lease

git reset --hard HEAD~1

# -m 1 keeps first parent (your branch)
git revert -m 1 <merge-commit-sha>
git push

# List stashes
git stash list

# Apply most recent
git stash pop

# Apply specific stash
git stash apply stash@{2}

# Recover dropped stash (search reflog)
git reflog | grep "WIP on"

# Backup before dangerous operations
git branch backup-before-rebase

# Use safer force push
git push --force-with-lease

# Commit early, commit often
# More recovery points = easier recovery

$ git reflog

abc1234 HEAD@{0}: commit: feat: Add auth
def5678 HEAD@{1}: checkout: moving from main to feature
ghi9012 HEAD@{2}: pull: Fast-forward
jkl3456 HEAD@{3}: reset: moving to HEAD~3
mno7890 HEAD@{4}: rebase: (finish)
pqr2345 HEAD@{5}: rebase: (start)

abc1234 HEAD@{0}: commit: feat: Add auth
───────  ────────  ─────── ──────────────
   │        │         │          │
   │        │         │          └── Description
   │        │         └───────────── Action type
   │        └─────────────────────── Position (0 = most recent)
   └──────────────────────────────── Commit SHA

# Search by message
git reflog | grep "important feature"

# Search by date
git reflog --since="2 hours ago"

# Search by author action
git reflog | grep "commit:"

$ git reflog
abc1234 HEAD@{0}: reset: moving to HEAD~5  # Bad reset!
def5678 HEAD@{1}: commit: Important work   # Lost commit

$ git reset --hard HEAD@{1}  # Recovered!

$ git reflog
abc1234 HEAD@{0}: rebase (finish)
def5678 HEAD@{1}: rebase (pick)
ghi9012 HEAD@{2}: rebase (start)     # Find pre-rebase state
jkl3456 HEAD@{3}: commit: My work    # This is what we want

$ git reset --hard HEAD@{3}  # Back to pre-rebase

# Find last commit on deleted branch
git reflog | grep "checkout: moving from deleted-branch"

# Recreate branch
git checkout -b recovered abc1234

# Reflog for specific branch
git reflog show feature-branch

# Reflog for remote tracking
git reflog show origin/main

# Default: 90 days for reachable, 30 days for unreachable
git config gc.reflogExpire          # Default: 90.days
git config gc.reflogExpireUnreachable  # Default: 30.days

# Keep forever (not recommended)
git config gc.reflogExpire never

[ ] main is up to date (`git pull origin main`)
[ ] No uncommitted changes (`git status` is clean)
[ ] Issue/ticket exists for the work
[ ] Branch name follows convention

# Valid patterns
issue/123-add-user-auth     # Linked to issue (preferred)
feature/oauth-integration   # No issue, feature work
fix/null-pointer-api        # Bug fix
hotfix/security-patch       # Urgent production fix

# Invalid patterns
my-branch                   # No prefix
ISSUE-123                   # Wrong format
feature/Add_User_Auth       # No underscores/capitals

# Check branch name format
BRANCH=$(git branch --show-current)

if [[ ! "$BRANCH" =~ ^(issue|feature|fix|hotfix|release)/ ]]; then
  echo "WARNING: Branch '$BRANCH' doesn't follow naming convention"
fi

[ ] Correct branch (not main/dev)
[ ] Branch tracks remote (`git push -u origin <branch>`)
[ ] Working directory is clean except intended changes

[ ] All tests pass locally
[ ] No debug code (console.log, print, debugger)
[ ] No secrets or credentials
[ ] Commits are atomic (one logical change each)
[ ] Commit messages follow conventional format

[ ] Branch rebased on latest main
[ ] No merge conflicts
[ ] CI passing on branch
[ ] Self-reviewed the diff
[ ] Issue linked in PR description

1. Create    → git checkout -b issue/123-feature
2. Work      → atomic commits, frequent pushes
3. Sync      → git fetch && git rebase origin/main
4. PR        → gh pr create
5. Review    → address feedback
6. Merge     → squash or rebase merge
7. Cleanup   → git branch -d issue/123-feature

# Accidentally committed to main?
# 1. Create branch from current state
git branch fix/my-changes

# 2. Reset main to origin
git reset --hard origin/main

# 3. Switch to new branch
git checkout fix/my-changes

[ ] Does ONE logical thing (no "and" in description)
[ ] Can be reverted independently
[ ] Leaves codebase in working state
[ ] Tests pass after this commit

BAD:  "Add auth and fix typos"           → Split into 2 commits
BAD:  "Refactor users, update tests"     → Split into 2 commits
BAD:  "WIP"                              → Finish or stash
GOOD: "feat(auth): Add JWT validation"   → Single concern

# What's staged (will be committed)
git diff --staged

# What's NOT staged (will NOT be committed)
git diff

# Files overview
git status

# Stage hunks selectively
git add -p

# Keybindings:
# y = stage this hunk
# n = skip this hunk
# s = split into smaller hunks
# e = edit hunk manually
# q = quit (staged so far remains)

<type>(<scope>): <description>

[optional body]

[optional footer]

[ ] Title < 50 characters
[ ] Title uses imperative mood ("Add" not "Added")
[ ] Title doesn't end with period
[ ] Body wraps at 72 characters
[ ] Body explains WHY, not WHAT
[ ] Footer references issues (Closes #123)

# Good
git commit -m "feat(api): Add rate limiting to /users endpoint"

# With body (use editor or heredoc)
git commit -m "$(cat <<'EOF'
fix(auth): Handle expired refresh tokens gracefully

Previously, expired refresh tokens caused 500 errors. Now returns
401 with clear error message and invalidates the session.

Closes #456
EOF
)"

# Verify staged content is correct
git diff --staged --stat

# Verify not committing to protected branch
BRANCH=$(git branch --show-current)
if [[ "$BRANCH" =~ ^(main|master|dev|develop)$ ]]; then
  echo "ERROR: Cannot commit directly to $BRANCH"
  exit 1
fi

# Check for debug code
git diff --staged | grep -E "(console\.log|debugger|print\(|pdb)" && \
  echo "WARNING: Debug code detected"

# Check for secrets
git diff --staged | grep -iE "(password|secret|api.?key|token)" && \
  echo "WARNING: Possible secrets detected"

# 1. Review changes
git status
git diff

# 2. Stage selectively
git add -p

# 3. Verify staged
git diff --staged

# 4. Commit with message
git commit -m "feat(scope): Description"

# 5. Verify commit
git log --oneline -1
git show --stat

# Keep changes staged
git reset --soft HEAD~1

# Keep changes unstaged
git reset HEAD~1

# Discard everything (DANGEROUS)
git reset --hard HEAD~1