| name | git-workflow |
| description | Use when making commits, creating branches, or managing Git operations. Ensures consistent Git practices and proper commit messages. |
Git Workflow
Core Principle
Maintain clean, readable Git history with meaningful commits and consistent branching practices.
When to Use This Skill
- Creating new branches
- Making commits
- Writing commit messages
- Merging branches
- Creating pull/merge requests
- Any Git operation
The Iron Laws
1. NO AI CO-AUTHOR ATTRIBUTION IN COMMITS
This is a firm policy. Commits represent human accountability.
2. NO COMMITS WITHOUT VERIFICATION
MANDATORY: Use verification-before-completion skill before EVERY commit.
Never commit without:
- ✅ All tests passing (unit, integration, e2e)
- ✅ Code quality checks passed
- ✅ Pre-commit hooks successful
- ✅ Self-review completed
- ✅ Verification checklist complete
3. SMALL, PRECISE COMMITS
One logical change per commit.
✅ Good commits:
feat(auth): add email validation to login formfix(api): handle null values in user profile endpointtest(checkout): add e2e tests for payment flow
❌ Bad commits:
feat: add login, fix bugs, update tests, refactor code- Large commits with multiple unrelated changes
- Commits without running tests
Why small commits:
- 🔍 Easier to review
- 🐛 Easier to find bugs (git bisect)
- ⏪ Easier to revert
- 📖 Clearer history
4. FRONTEND + BACKEND = BOTH TESTS REQUIRED
When changes affect both frontend and backend:
MANDATORY before commit:
1. ✅ Backend tests pass (unit + integration)
2. ✅ E2E tests pass (full user flow)
3. ✅ API tests pass (if API changed)
4. ✅ Frontend tests pass (component + integration)
Never commit:
- ❌ Backend changes without backend tests
- ❌ Frontend changes without e2e tests
- ❌ API changes without both backend AND e2e tests
- ❌ Changes that break existing tests
5. PRE-COMMIT HOOKS ARE MANDATORY
Every project MUST have pre-commit hooks.
Minimum hooks required:
- Code formatting (Prettier, Black, PHP CS Fixer)
- Linting (ESLint, Ruff, PHPStan)
- Type checking (TypeScript, mypy, Psalm)
- Test execution (if files changed)
- No secrets/credentials check
See: .claude/skills/safety/pre-commit-hooks/SKILL.md for setup
Git Commit Message Format
Structure
<type>(<scope>): <subject>
<body>
<footer>
Type
Must be one of:
feat: New featurefix: Bug fixdocs: Documentation only changesstyle: Code style changes (formatting, missing semi-colons, etc)refactor: Code refactoring (no functional changes)perf: Performance improvementstest: Adding or updating testsbuild: Build system or dependenciesci: CI/CD changeschore: Other changes (gitignore, etc)
Scope (Optional)
Component or module affected:
auth: Authenticationapi: API endpointsdatabase: Database changesui: User interfacetests: Test files
Subject
- Use imperative mood: "add" not "added" or "adds"
- Don't capitalize first letter
- No period at end
- Max 50 characters
- Be specific and concise
Body (Optional but Recommended)
- Explain WHAT and WHY, not HOW
- Wrap at 72 characters
- Separate from subject with blank line
- Use bullet points if multiple items
Footer (Optional)
- Breaking changes:
BREAKING CHANGE: description
- Issue references:
Closes #123, Fixes #456
- NO AI co-author attribution
Commit Message Examples
Good Examples
feat(auth): add JWT token-based authentication
Implement stateless authentication using Laravel Sanctum:
- User registration with email/password
- Login returns bearer token
- Protected routes use auth:sanctum middleware
- Token revocation on logout
Closes #45
fix(api): resolve N+1 query in user list endpoint
Added eager loading for user relationships to prevent
multiple database queries per user.
Performance improvement: 50+ queries → 2 queries
Fixes #78
docs: update README with authentication setup
Add step-by-step guide for:
- Installing Sanctum
- Configuring .env variables
- Running migrations
- Testing authentication
Bad Examples
❌ Updated stuff
- Too vague, no context
❌ Added authentication.
- Capitalized, has period, no detail
❌ feat: add auth with JWT and social login and fix bugs and update docs
- Too long, multiple unrelated changes
❌ WIP
- Meaningless, what is in progress?
❌ fix: fixed the bug
- Redundant, no detail about which bug
Branching Strategy
Branch Naming Convention
<type>/<short-description>
Types:
feature/ - New featuresfix/ - Bug fixeshotfix/ - Urgent production fixesrefactor/ - Code refactoringdocs/ - Documentationtest/ - Test-related work
Examples:
feature/jwt-authenticationfix/login-validation-errorhotfix/security-patch-xssrefactor/user-controllerdocs/api-documentation
Branch Workflow
Creating a New Branch
git checkout main
git pull origin main
git checkout -b feature/authentication
git checkout -b fix/login-bug develop
Working on a Branch
[edit files]
git add path/to/file.php
git add .
git commit -m "feat(auth): add user registration endpoint
Implement registration with email/password validation.
Returns JWT token on successful registration.
Closes #23"
git push -u origin feature/authentication
Updating Branch with Latest Changes
git checkout main
git pull origin main
git checkout feature/authentication
git merge main
git checkout feature/authentication
git fetch origin
git rebase origin/main
Finishing a Branch
See finishing-a-development-branch skill for complete checklist.
Git Best Practices
Commit Frequency
- Commit often: Small, focused commits
- Commit working code: Each commit should be functional
- Commit before major refactors: So you can rollback if needed
What to Commit
✅ DO commit:
- Source code
- Configuration files (without secrets)
- Tests
- Documentation
- Migrations
- .env.example (template, no secrets)
❌ DON'T commit:
- .env (contains secrets)
- node_modules/, vendor/
- Build artifacts (dist/, build/)
- IDE-specific files (.idea/, .vscode/)
- Log files
- Database files (*.sqlite, backups/)
- Temporary files
.gitignore
Ensure proper .gitignore for your framework:
Laravel:
/vendor/
/node_modules/
.env
.env.*.local
/storage/*.key
/public/hot
/public/storage
/storage/logs/
/bootstrap/cache/*.php
backups/
Node.js:
node_modules/
.env
.env.*.local
dist/
build/
*.log
.DS_Store
Python:
__pycache__/
*.pyc
.env
.venv/
venv/
*.log
.pytest_cache/
.coverage
Commit Workflow Checklist
Before committing:
Advanced Git Operations
Amending Last Commit
git add forgotten-file.php
git commit --amend --no-edit
git commit --amend -m "new commit message"
Undoing Changes
git restore path/to/file.php
git restore --staged path/to/file.php
git reset HEAD~1
git reset --hard HEAD~1
Stashing Changes
git stash
git stash list
git stash pop
git stash apply stash@{0}
Cherry-picking Commits
git cherry-pick <commit-hash>
GitHub/GitLab Integration
Creating Pull/Merge Request
GitHub:
gh pr create --title "feat(auth): Add JWT authentication" --body "Implements user authentication with JWT tokens
- Registration endpoint
- Login endpoint
- Protected routes
- Tests included
Closes #45"
GitLab:
glab mr create --title "feat(auth): Add JWT authentication" --description "Implements user authentication with JWT tokens
- Registration endpoint
- Login endpoint
- Protected routes
- Tests included
Closes #45"
Commit Message in PR/MR
Use the same format as commit messages:
## What
Implements JWT authentication for API
## Why
Needed stateless authentication for mobile app support
## Changes
- Added Laravel Sanctum
- User registration endpoint
- Login/logout endpoints
- Auth middleware on protected routes
- 15 tests covering auth flows
## Testing
- All tests pass (127 total)
- Manual testing completed
- API documentation updated
Closes #45
Integration with Other Skills
Use before committing:
code-review - Review your changesverification-before-completion - Ensure everything worksdatabase-backup - Before running tests
Related skills:
finishing-a-development-branch - Complete checklist before PR/MRgit-worktrees - Working on multiple branches
Red Flags (Bad Git Practices)
- ❌ Committing directly to main/master
- ❌ Vague commit messages ("fix", "update", "WIP")
- ❌ Committing secrets (.env file)
- ❌ Committing broken code
- ❌ Huge commits with unrelated changes
- ❌ Not testing before committing
- ❌ Including AI co-author attribution
Common Rationalizations to Reject
- ❌ "I'll write a proper message later" → Write it now
- ❌ "Just a quick fix, doesn't need good message" → All commits need good messages
- ❌ "I'll clean up history before merging" → Don't rely on it, do it right first time
- ❌ "Adding AI attribution gives credit" → Humans are accountable, not AI
Authority
This skill is based on:
- Git best practices (Conventional Commits standard)
- Industry standard: All professional teams use consistent commit practices
- Legal/accountability: Commits represent human responsibility
- CodeAssist policy: NO AI attribution in commits
Social Proof: Companies like Google, Microsoft, and GitHub use commit message conventions.
Your Commitment
Before making commits:
Bottom Line: Git history is documentation. Write it for humans who will read it later (including future you). Clean Git history makes debugging, code review, and collaboration easier.
