| name | git-workflow |
| description | Git best practices, branching strategies, commit conventions, and PR workflows. Use when reviewing git history, writing commits, setting up branching strategy, or improving git practices. Triggers on "git best practices", "commit message", "branching strategy", or "PR workflow". |
| license | MIT |
| metadata | {"author":"AsyrafHussin","version":"1.2.0"} |
Git Workflow
Git best practices, commit conventions, branching strategies, and pull request workflows. Guidelines for maintaining a clean, useful git history.
When to Apply
Reference these guidelines when:
- Writing commit messages
- Creating branches
- Setting up git workflows
- Reviewing pull requests
- Maintaining git history
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|
| 1 | Commit Messages | CRITICAL | commit- |
| 2 | Branching Strategy | HIGH | branch- |
| 3 | Pull Requests | HIGH | pr- |
| 4 | History Management | MEDIUM | history- |
| 5 | Collaboration | MEDIUM | collab- |
Quick Reference
1. Commit Messages (CRITICAL)
commit-conventional - Use conventional commitscommit-atomic - Atomic commits (one logical change)commit-present-tense - Use imperative present tensecommit-meaningful - Descriptive, meaningful messagescommit-body - Add body for complex changescommit-references - Reference issues/ticketscommit-git-hooks - Enforce standards with Husky + commitlint
2. Branching Strategy (HIGH)
branch-naming - Consistent branch namingbranch-feature - Feature branch workflowbranch-main-protected - Protect main branchbranch-short-lived - Keep branches short-livedbranch-delete-merged - Delete merged branchesbranch-release - Release branch strategybranch-workflow-strategies - GitFlow vs GitHub Flow vs Trunk-Basedbranch-monorepo - Monorepo git workflows
3. Pull Requests (HIGH)
pr-small - Keep PRs small and focusedpr-description - Write clear descriptionspr-reviewers - Request appropriate reviewerspr-ci-pass - Ensure CI passespr-squash - Squash when appropriatepr-draft - Use draft PRs for WIP and early feedback
4. History Management (MEDIUM)
history-rebase - Rebase vs mergehistory-no-force-push - Avoid force push to shared brancheshistory-clean - Keep history cleanhistory-tags - Use tags for releaseshistory-worktree - Work on multiple branches with git worktree
5. Collaboration (MEDIUM)
collab-code-review - Effective code reviewscollab-conflicts - Handle merge conflictscollab-communication - Communicate changescollab-gitignore - .gitignore best practices
Essential Guidelines
Conventional Commits
# Format
<type>(<scope>): <subject>
<body>
<footer>
Types
| Type | Description |
|---|
feat | New feature |
fix | Bug fix |
docs | Documentation only |
style | Formatting, no code change |
refactor | Code change, no feature/fix |
perf | Performance improvement |
test | Adding/updating tests |
chore | Maintenance, dependencies |
ci | CI/CD changes |
build | Build system changes |
revert | Revert previous commit |
Examples
feat(auth): add password reset functionality
fix(cart): resolve quantity update race condition
docs(readme): add installation instructions
refactor(api): extract validation into middleware
test(user): add unit tests for registration
chore(deps): update dependencies to latest versions
feat(orders): implement order cancellation
Add ability for users to cancel pending orders within 24 hours.
Cancelled orders trigger refund process automatically.
Closes
BREAKING CHANGE: Order status enum now includes 'cancelled'
fix bug
update
WIP
asdfasdf
changes
misc fixes
Branch Naming
feature/user-authentication
feature/JIRA-123-password-reset
fix/cart-total-calculation
fix/issue-456-login-redirect
hotfix/security-patch
docs/api-documentation
refactor/database-queries
chore/update-dependencies
new-feature
john-branch
test
fix
temp
asdf
Branch Workflow
main
develop
feature/*
fix/*
hotfix/*
release/*
git checkout main
git pull origin main
git checkout -b feature/user-profile
git add .
git commit -m "feat(profile): add profile page"
git fetch origin
git rebase origin/main
git push -u origin feature/user-profile
Atomic Commits
git commit -m "Add login, fix header, update deps"
git commit -m "feat(auth): add login page"
git commit -m "fix(header): correct navigation alignment"
git commit -m "chore(deps): update React to v18.2"
Commit Frequently, Push Regularly
git commit -m "feat(cart): add product to cart"
git commit -m "feat(cart): display cart item count"
git commit -m "feat(cart): implement remove item"
git commit -m "test(cart): add unit tests"
git commit -m "feat: implement entire shopping cart"
Pull Request Best Practices
PR Title
# Format (like commit)
<type>(<scope>): <description>
# ✅ Good PR titles
feat(auth): implement OAuth2 login
fix(checkout): resolve payment processing error
docs(api): add endpoint documentation
# ❌ Bad PR titles
Update
Fix stuff
WIP
PR Description Template
## Summary
Brief description of what this PR does.
## Changes
- Added user authentication endpoints
- Implemented JWT token generation
- Added password hashing with bcrypt
## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
## Screenshots (if UI changes)
[Add screenshots here]
## Related Issues
Closes #123
Related to #456
## Checklist
- [ ] Code follows project conventions
- [ ] Self-review completed
- [ ] Tests added/updated
- [ ] Documentation updated
Keep PRs Small
# ✅ Focused PRs
PR #1: Add user model and migrations
PR #2: Implement user registration endpoint
PR #3: Add email verification
PR #4: Implement login/logout
# ❌ Large unfocused PR
PR #1: Add entire user authentication system
(2000+ lines, 50+ files)
Rebase vs Merge
git checkout feature/my-feature
git fetch origin
git rebase origin/main
git push --force-with-lease
git checkout main
git merge --no-ff feature/my-feature
git push --force origin main
Interactive Rebase (Clean Up)
git rebase -i HEAD~5
pick abc123 feat: add login page
squash def456 fix typo
squash ghi789 more fixes
pick jkl012 feat: add logout
Handling Conflicts
git rebase origin/main
git add file.ts
git rebase --continue
git rebase --abort
Git Hooks
npm run lint
npm run test:unit
npx commitlint --edit $1
module.exports = {
extends: ['@commitlint/config-conventional'],
};
Tagging Releases
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0
git tag -l "v1.*"
v1.0.0
v1.0.0-beta.1
v1.0.0-rc.1
.gitignore Best Practices
# Dependencies
node_modules/
vendor/
# Build outputs
dist/
build/
.next/
# Environment files
.env
.env.local
.env.*.local
# IDE
.idea/
.vscode/
*.swp
# OS files
.DS_Store
Thumbs.db
# Logs
*.log
logs/
# Test coverage
coverage/
# Cache
.cache/
*.cache
Useful Git Commands
git log --oneline --graph --all
git diff --staged
git diff HEAD~1
git reset --soft HEAD~1
git checkout -- file.ts
git restore file.ts
git stash
git stash pop
git stash list
git cherry-pick abc123
git blame file.ts
git log --grep="fix"
git log -S "functionName"
Output Format
When reviewing git practices, output findings:
[category] Description of issue or suggestion
Example:
[commit] Use imperative mood: "Add feature" not "Added feature"
[branch] Branch name 'test' should follow pattern: feature/description
[pr] PR is too large (50+ files), consider splitting
How to Use
Read individual rule files for detailed explanations:
rules/commit-conventional-format.md
rules/branch-naming-convention.md
rules/pr-small-focused.md
References
Examples from Well-Known Projects
Learn from projects with excellent git practices:
- Linux Kernel - Detailed commit messages and patch workflow
- React - Conventional commits and thorough PR reviews
- Vue.js - Clean commit history and good PR templates
- TypeScript - Structured branching and clear release process
- Next.js - Conventional commits and automated releases
Configuration Examples
Commitlint
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [
2,
'always',
['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'chore', 'ci', 'build', 'revert']
],
'subject-max-length': [2, 'always', 72],
'body-max-line-length': [2, 'always', 100]
}
};
Husky Git Hooks
npx commitlint --edit $1
npm run lint
npm test
GitHub PR Template
# .github/PULL_REQUEST_TEMPLATE.md
## Summary
Brief description of changes
## Changes
- List key changes
- One per line
## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
## Related
Closes #issue-number
Metadata
Skill Version: 1.2.0
Last Updated: 2026-03-08
Total Rules: 31
Categories: 5 (Commit Messages, Branching Strategy, Pull Requests, History Management, Collaboration)
Compatible With:
- Git 2.0+
- GitHub, GitLab, Bitbucket, Azure DevOps
Recommended Tools:
License
MIT License. This skill is provided as-is for educational and development purposes.
