| 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
git checkout -b feat/user-authentication
git add src/auth.py src/models/user.py tests/test_auth.py
git commit --amend --no-edit
git rebase -i HEAD~3
git merge --squash feat/user-authentication
git reset --soft HEAD~1
git diff HEAD~1 HEAD --stat
git bisect start
git bisect bad
git bisect good v1.0.0
.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"