git-workflow

Conventional Commit Format

# BAD: vague, no type
git commit -m "changes"

# GOOD: clear type, scope, imperative mood
git commit -m "feat(auth): add OAuth2 login flow"
git commit -m "fix(api): handle null response in getUserData"
git commit -m "docs(readme): update installation steps"

Format: type(scope): description

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore

Breaking changes:

git commit -m "feat(api)!: remove deprecated v1 endpoints"
# Or in body:
git commit -m "feat(api): migrate to v2 endpoints

BREAKING CHANGE: v1 endpoints removed, use v2"

Setup Commit Linting

# Install commitlint
npm install --save-dev @commitlint/config-conventional @commitlint/cli

# Create config
cat > commitlint.config.js <<'EOF'
module.exports = { extends: ['@commitlint/config-conventional'] };
EOF

# Hook with Husky
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'

Merge vs Rebase Decision Tree

Question: Is the branch shared with others?
│
├─ YES → USE MERGE
│   └─ git merge feature-branch
│      (preserves branch history, safer for collaboration)
│
└─ NO → Ask: Do you want linear history?
    │
    ├─ YES → USE REBASE
    │   └─ git rebase main
    │      (clean history, better for bisect)
    │
    └─ NO → USE MERGE
        └─ git merge --no-ff feature-branch
           (preserves feature branch context)

Rebase workflow for feature branches:

# Daily sync (before starting work)
git checkout feature-branch
git fetch origin
git rebase origin/main

# Interactive cleanup before PR
git rebase -i origin/main
# Squash "fix typo", "wip" commits

# After PR approval
git checkout main
git merge --ff-only feature-branch  # or squash in GitHub UI

When rebase conflicts occur:

# BAD: panic and force push to main
git push --force origin main  # NEVER DO THIS

# GOOD: resolve, test, continue
git rebase main
# Fix conflicts in files
git add resolved-file.js
git rebase --continue
npm test  # Always test after resolving
git push --force-with-lease origin feature-branch