git-workflow

name	git-workflow
description	Git workflow best practices. Use when committing code, managing branches, writing commit messages, or setting up git workflows.

Git Workflow Patterns

Commit Message Format (Conventional Commits)

<type>(<scope>): <short summary>

[optional body: WHY this change was made]

[optional footer: BREAKING CHANGE, closes #issue]

Types:

• feat: New feature
• fix: Bug fix
• refactor: Code change that doesn't add features or fix bugs
• test: Adding or updating tests
• docs: Documentation only
• chore: Build, deps, config changes
• perf: Performance improvement
• ci: CI/CD changes

Examples:

feat(auth): add JWT refresh token rotation

Implement sliding refresh tokens to improve security.
Old refresh tokens are invalidated immediately on use.

Closes #123

---

fix(api): return 404 when user not found instead of 500

The get_user endpoint was crashing when user_id didn't exist
because db.get() returns None and we were accessing None.email.

---

refactor(models): extract TimestampMixin from all models

All models had duplicate created_at/updated_at columns.
Extracted to reusable mixin to DRY the code.

Branch Strategy (GitHub Flow — simple)

main              # Always deployable
feature/          # New features
fix/              # Bug fixes
chore/            # Maintenance

# Never commit directly to main
# Every change = branch → PR → review → merge

Commands

# Start new feature
git checkout -b feat/user-authentication

# Stage only relevant files (never git add .)
git add src/auth.py src/models/user.py tests/test_auth.py

# Amend last commit (before push)
git commit --amend --no-edit

# Interactive rebase to clean up commits
git rebase -i HEAD~3

# Squash all feature commits before merge
git merge --squash feat/user-authentication

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

# See what changed in last commit
git diff HEAD~1 HEAD --stat

# Find when a bug was introduced
git bisect start
git bisect bad           # current commit has bug
git bisect good v1.0.0   # known good commit

.gitignore (Python project)

__pycache__/
*.pyc
.env
.env.local
*.egg-info/
dist/
build/
.venv/
venv/
.pytest_cache/
.coverage
htmlcov/
*.log
.DS_Store

Pre-commit Hooks (.pre-commit-config.yaml)

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.3.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.9.0
    hooks:
      - id: mypy

Rules

• Commit early and often — small, focused commits
• Each commit should leave the codebase in a working state
• Write commit messages in imperative: "Add auth" not "Added auth"
• Never commit: .env, secrets, API keys, large binaries, generated files
• Pull before push (git pull --rebase to avoid merge commits)
• Review your own diff before committing: git diff --staged
• Tag releases: git tag -a v1.0.0 -m "First stable release"