| name | git-workflow-skills |
| description | Provides standardized Git workflows, commit message conventions, branching strategies, and collaboration patterns for all agents performing Git operations. Use when creating commits, choosing branching strategies, creating PRs, performing git operations (merge vs rebase), or handling git collaboration workflows. |
| license | MIT |
Git Workflow Skills
Overview
This skill provides comprehensive Git workflow guidance for agents performing version control operations. It covers commit message conventions (Conventional Commits), branching strategies (GitHub Flow, Git Flow, Trunk-based), PR best practices, git operation patterns (merge vs rebase vs squash), collaboration workflows, and security considerations.
Use this skill whenever performing git operations to ensure consistency, maintainability, and professional quality across all projects.
Core Principles
- Clarity Over Cleverness: Commit messages and branch names should be immediately understandable
- Atomic Commits: One logical change per commit (enables easy revert, clear history)
- Safety First: Never commit secrets, avoid force push to protected branches
- Team Consistency: Follow project conventions, communicate through commits and PRs
- History Matters: Clean, readable history is a project asset
Commit Message Conventions
Conventional Commits Format
Follow the Conventional Commits specification for all commit messages:
<type>(<scope>): <subject>
<body>
<footer>
Components:
- type (required): feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert
- scope (optional): Component/module affected (e.g., auth, api, ui, database)
- subject (required): Brief description (50 chars max, imperative mood, no period)
- body (optional): Detailed explanation (wrap at 72 chars)
- footer (optional): Breaking changes, issue references
Commit Types
feat: New feature for the user
feat(auth): add OAuth2 login support
Implement OAuth2 authentication flow with Google and GitHub providers.
Includes token refresh mechanism and session management.
Closes #142
fix: Bug fix for the user
fix(api): prevent race condition in user creation
Add database transaction lock to prevent duplicate user records
when multiple requests arrive simultaneously.
Fixes #238
docs: Documentation changes only
docs(readme): add installation instructions for Windows
Include troubleshooting section for common Windows-specific issues.
style: Code formatting, missing semicolons, whitespace (no logic change)
style(components): format with prettier, remove trailing whitespace
refactor: Code change that neither fixes bug nor adds feature
refactor(database): extract query builder into separate class
Improve code organization and testability by separating query
construction from execution logic.
test: Adding or updating tests
test(auth): add integration tests for OAuth flow
chore: Maintenance tasks, dependency updates, build configuration
chore(deps): upgrade React from 18.2.0 to 18.3.0
perf: Performance improvement
perf(api): add database indexes for user queries
Reduce user lookup time from 250ms to 15ms by indexing email column.
ci: CI/CD configuration changes
ci(github): add automated deployment to staging environment
build: Build system or external dependency changes
build(webpack): optimize bundle size with code splitting
revert: Reverts a previous commit
revert: feat(auth): add OAuth2 login support
This reverts commit a1b2c3d4. OAuth implementation needs rework
due to security concerns identified in code review.
Breaking Changes
Indicate breaking changes with ! after type/scope and in footer:
feat(api)!: change user endpoint response format
BREAKING CHANGE: User API now returns `userId` instead of `id`.
Clients must update to use new field name.
Migration guide: https://docs.example.com/migration-v2
Good vs Bad Commit Messages
❌ Bad Examples:
Update files
Fix bug
WIP
asdf
Changed some stuff
Fixed it
✅ Good Examples:
feat(search): add fuzzy matching for product queries
fix(checkout): calculate tax correctly for international orders
docs(api): update authentication examples
refactor(utils): extract date formatting into helper function
Multi-line Commit Messages
Use multi-line messages for non-trivial changes:
feat(notifications): implement real-time notification system
Add WebSocket-based notification delivery for user actions.
Includes:
- WebSocket server with connection pooling
- Client-side notification queue with retry logic
- Notification preferences UI
- Email fallback for offline users
Performance: Handles 10k concurrent connections with <100ms latency.
Closes #156, #187
Integration with Claude Code
When agents create commits, always:
- Analyze
git diff to understand changes
- Determine appropriate type (feat, fix, docs, etc.)
- Identify scope from files changed
- Write clear subject line (imperative mood)
- Add body for non-trivial changes explaining "why"
- Include Claude Code footer:
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Branching Strategies
Strategy Selection Guide
Choose GitHub Flow (recommended for most projects):
- ✅ Continuous deployment
- ✅ Small to medium teams
- ✅ Web applications
- ✅ Simple release process
Choose Git Flow:
- ✅ Scheduled releases
- ✅ Multiple production versions
- ✅ Enterprise software
- ✅ Complex release management
Choose Trunk-based Development:
- ✅ Very frequent deployments
- ✅ Strong CI/CD pipeline
- ✅ Experienced team
- ✅ Feature flags in place
GitHub Flow (Recommended)
Branches:
main: Always deployable, protectedfeature/*: Short-lived feature branches
Workflow:
- Create feature branch from
main: feature/add-user-search
- Commit changes with conventional commits
- Push to remote and create PR
- Code review and CI checks
- Merge to
main (squash or merge commit)
- Deploy
main to production
- Delete feature branch
Branch naming:
feature/add-oauth-login
feature/user-profile-page
bugfix/fix-login-redirect
hotfix/patch-security-vulnerability
docs/update-api-documentation
Example workflow:
git checkout main
git pull origin main
git checkout -b feature/add-search-filter
git add src/components/SearchFilter.tsx
git commit -m "feat(search): add category filter to search UI"
git push -u origin feature/add-search-filter
gh pr create --title "Add category filter to search" --body "..."
git checkout main
git pull origin main
git branch -d feature/add-search-filter
Git Flow
Branches:
main: Production releases onlydevelop: Integration branchfeature/*: Feature developmentrelease/*: Release preparationhotfix/*: Production hotfixes
Workflow:
- Feature: Branch from
develop, merge back to develop
- Release: Branch from
develop, merge to main and develop
- Hotfix: Branch from
main, merge to main and develop
Use when: Managing multiple release versions, scheduled releases, complex projects
Example:
git checkout develop
git checkout -b feature/payment-integration
git checkout develop
git merge --no-ff feature/payment-integration
git checkout -b release/1.2.0 develop
git checkout main
git merge --no-ff release/1.2.0
git tag -a v1.2.0
git checkout develop
git merge --no-ff release/1.2.0
Trunk-based Development
Branches:
main: The trunk, always deployablefeature/*: Very short-lived (< 1 day)
Workflow:
- Create small feature branch
- Commit frequently
- Merge to
main within hours/1 day
- Use feature flags for incomplete features
- Deploy
main frequently (multiple times per day)
Requirements:
- Strong automated testing
- Feature flag system
- Mature CI/CD pipeline
- Team discipline
PR/MR Best Practices
PR Title Format
Use conventional commit format:
feat(auth): add OAuth2 login support
fix(api): prevent race condition in user creation
docs(readme): add installation instructions
PR Description Template
## Summary
Brief description of what this PR does and why.
## Changes
- Add OAuth2 authentication with Google and GitHub
- Implement token refresh mechanism
- Add session management
- Update user model to store OAuth tokens
## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
## Testing
- [x] Unit tests added/updated
- [x] Integration tests added/updated
- [x] Manual testing completed
- [ ] Performance testing completed
## Test Plan
1. Test Google OAuth login flow
2. Test GitHub OAuth login flow
3. Verify token refresh after expiry
4. Test session persistence across browser restarts
## Screenshots (if applicable)
[Add screenshots of UI changes]
## Breaking Changes
None
## Related Issues
Closes #142
Related to #156
## Checklist
- [x] Code follows project style guidelines
- [x] Self-review completed
- [x] Comments added for complex logic
- [x] Documentation updated
- [x] No new warnings generated
- [x] Tests pass locally
- [x] Dependent changes merged
PR Size Guidelines
Optimal PR size: 200-400 lines changed
Maximum recommended: 800 lines changed
When PR is too large:
- Split into multiple PRs (preferred)
- Add detailed description and comments
- Schedule synchronous review session
- Break into reviewable sections
Draft PRs
Create draft PR when:
- Seeking early feedback on approach
- Work in progress, not ready for review
- Demonstrating proof of concept
- Collaborating on complex feature
Mark as "Ready for review" when:
- All tests pass
- Code is self-reviewed
- Documentation is updated
- Ready for merge after approval
Review Request Etiquette
- Self-review first: Review your own PR before requesting review
- Provide context: Explain the "why" in description
- Highlight concerns: Point out areas needing special attention
- Request specific reviewers: Tag domain experts
- Be responsive: Address feedback promptly
- Be respectful: Thank reviewers, engage constructively
Addressing Review Comments
When making changes:
git add src/auth/oauth.ts
git commit -m "refactor(auth): extract token validation per review feedback"
git push origin feature/add-oauth-login
When resolving comments:
- ✅ "Done, updated in commit abc123"
- ✅ "Good point, refactored to use helper function"
- ✅ "Created issue #245 to track this separately"
- ❌ "Done" (without context)
- ❌ Resolving without making changes
Git Operations Patterns
Merge vs Rebase vs Squash
Merge Commit (git merge --no-ff):
- When: Preserving complete feature branch history
- Pros: Full history preserved, clear feature boundaries
- Cons: Cluttered history with many merge commits
- Use for: Long-lived feature branches, collaborative branches
git checkout main
git merge --no-ff feature/add-search
Rebase (git rebase):
- When: Keeping feature branch up to date with main
- Pros: Clean linear history, no merge commits
- Cons: Rewrites history (don't rebase public branches)
- Use for: Updating feature branch, cleaning up local commits
git checkout feature/add-search
git rebase main
git rebase -i HEAD~5
Squash Merge (git merge --squash):
- When: Merging feature branch with many commits
- Pros: Clean main history, one commit per feature
- Cons: Loses detailed feature development history
- Use for: Feature branches with many WIP commits
git checkout main
git merge --squash feature/add-search
git commit -m "feat(search): add advanced search functionality"
Decision Matrix
| Scenario | Operation | Reasoning |
|---|
| Update feature branch with main | Rebase | Keep linear history |
| Merge feature to main (GitHub Flow) | Squash | Clean main history |
| Merge feature to main (Git Flow) | Merge commit | Preserve feature history |
| Clean up local commits before PR | Interactive rebase | Present clean history |
| Integrate long-lived branch | Merge commit | Preserve collaboration history |
| Apply single commit from another branch | Cherry-pick | Selective integration |
Keeping History Clean
Before creating PR:
git rebase -i main
pick a1b2c3d feat(search): add search component
fixup e4f5g6h WIP: fix typo
fixup h7i8j9k WIP: update tests
pick k0l1m2n feat(search): add filters
Commit message guidelines for clean history:
- Each commit should be self-contained and functional
- Commit message should describe the complete change
- Avoid "WIP", "temp", "fix typo" commits in final history
- Group related changes into logical commits
Force Push Safety
❌ Never force push to:
main / masterdevelop- Any protected branch
- Any branch others are working on
✅ Safe to force push to:
- Your own feature branch (before PR review)
- After interactive rebase on personal branch
When force push is needed:
git push --force-with-lease origin feature/add-search
--force-with-lease: Safer than --force, prevents overwriting others' work
Cherry-pick Use Cases
When to use cherry-pick:
- Apply hotfix to multiple branches
- Selectively port features across branches
- Recover commits from abandoned branch
Example:
git cherry-pick a1b2c3d
git cherry-pick a1b2c3d..e4f5g6h
git cherry-pick -n a1b2c3d
Collaboration Workflows
