Git Workflow Expert Skill

Git Workflow Expert

This skill provides guidance on commit standards and PR best practices.

🔧 Commit Standards

Conventional Commits

Follow the Conventional Commits specification:

<type>(<scope>): <subject>

[optional body]

[optional footer]

Commit Types

# New feature
git commit -m "feat(auth): add JWT token refresh mechanism"

# Bug fix
git commit -m "fix(api): handle null response appropriately"

# Documentation
git commit -m "docs(readme): update installation instructions"

# Performance improvement
git commit -m "perf(db): optimize query performance"

# Code refactoring
git commit -m "refactor(core): extract validation logic"

# Testing
git commit -m "test(auth): add unit tests for login flow"

# Build/tooling
git commit -m "build(deps): upgrade react to v18"

# CI/CD
git commit -m "ci(github): add automated deployment workflow"

# Chores
git commit -m "chore(deps): update development dependencies"

# Style changes (formatting, etc.)
git commit -m "style(components): format with prettier"

Commit Type Reference

| Type | Description | Example | |------|-------------|---------| | feat | New feature | Adding user authentication | | fix | Bug fix | Fixing null pointer error | | docs | Documentation only | Update README | | style | Formatting changes | Code formatting, no logic change | | refactor | Code refactoring | Restructure without behavior change | | perf | Performance improvement | Optimize algorithm | | test | Adding/updating tests | Add unit tests | | build | Build system changes | Update webpack config | | ci | CI/CD changes | Update GitHub Actions | | chore | Maintenance tasks | Update dependencies | | revert | Revert previous commit | Revert "feat: add feature" |

Commit Message Guidelines

Subject line:

Use imperative mood ("add" not "added" or "adds")
Don't capitalize first letter
No period at the end
Maximum 50 characters

Body:

Wrap at 72 characters
Explain what and why, not how
Use bullet points for multiple changes

Example:

git commit -m "$(cat <<'EOF'
feat(api): add user profile endpoint

- Add GET /api/users/:id endpoint
- Include avatar URL in response
- Add rate limiting (100 req/min)

This allows frontend to fetch user details
without additional API calls.

Closes #123
EOF
)"

Commit Trailers

Add metadata to commits using trailers:

# Reference GitHub issue
git commit --trailer "Github-Issue: #123"

# Credit bug reporter
git commit --trailer "Reported-by: John Doe <john@example.com>"

# Reference related commits
git commit --trailer "See-also: abc123"

# Co-author
git commit --trailer "Co-authored-by: Jane Smith <jane@example.com>"

Example with multiple trailers:

git commit -m "$(cat <<'EOF'
fix(auth): resolve token expiration issue

Fixed bug where expired tokens weren't properly
refreshed, causing users to be logged out unexpectedly.

Github-Issue: #456
Reported-by: John Doe <john@example.com>
Reviewed-by: Jane Smith <jane@example.com>
EOF
)"

📝 Pull Request Guidelines

PR Title

Follow the same format as commit messages:

<type>(<scope>): <description>

Examples:

feat(auth): add OAuth2 authentication
fix(api): resolve race condition in data sync
docs(contributing): update contributor guidelines

PR Description Template

## Summary
Brief description of changes (1-3 sentences)

## Changes
- Bullet point list of main changes
- Focus on what and why, not implementation details
- Keep it high-level

## Test Plan
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing performed
- [ ] Edge cases covered

## Breaking Changes
List any breaking changes (if applicable)

## Related Issues
Closes #123
Related to #456

## Screenshots/Videos
(if applicable)

PR Best Practices

Keep PRs small - Easier to review, faster to merge
One feature per PR - Don't mix unrelated changes
Update documentation - Keep docs in sync with code
Add tests - Don't merge without test coverage
Respond to reviews - Address feedback promptly
Squash commits - Clean up commit history before merge
Delete branch - Clean up after merge

PR Review Checklist

Before requesting review:

[ ] All tests pass
[ ] Code is formatted (linter passes)
[ ] Documentation updated
[ ] No console.log or debug code
[ ] Type safety verified (TypeScript)
[ ] Breaking changes documented

For reviewers:

[ ] Code follows project conventions
[ ] Logic is clear and maintainable
[ ] Edge cases are handled
[ ] Tests are adequate
[ ] No security vulnerabilities
[ ] Performance considerations addressed

🎯 Git Workflow Checklist

Daily workflow checklist:

[ ] Pull latest changes: git pull
[ ] Create feature branch
[ ] Make atomic commits with conventional format
[ ] Write meaningful commit messages
[ ] Push regularly: git push
[ ] Create PR with proper description
[ ] Address review feedback
[ ] Squash commits if needed
[ ] Merge and delete branch

💡 Advanced Git Tips

Interactive Rebase

# Clean up last 3 commits
git rebase -i HEAD~3

# Rebase onto main
git rebase -i main

Cherry-pick Commits

# Apply specific commit to current branch
git cherry-pick abc123

# Cherry-pick without committing
git cherry-pick --no-commit abc123

Stash Management

# Stash with message
git stash push -m "WIP: feature in progress"

# List stashes
git stash list

# Apply and drop stash
git stash pop

# Apply specific stash
git stash apply stash@{0}

Bisect for Bug Hunting

# Start bisect
git bisect start

# Mark current as bad
git bisect bad

# Mark known good commit
git bisect good abc123

# Let git find the culprit
# Test each commit and mark good/bad
git bisect good  # or bad

# End bisect
git bisect reset

🚫 Common Mistakes to Avoid

❌ Don't:

Commit directly to main/master
Use vague commit messages ("fix bug", "update")
Mix unrelated changes in one commit
Forget to pull before pushing
Leave WIP commits in PR
Skip commit message body for complex changes

✅ Do:

Use feature branches
Write descriptive conventional commits
Make atomic commits (one logical change)
Pull regularly and before pushing
Squash/reword commits before merging
Provide context in commit body

Agent Skills: Git Workflow Expert

Install this agent skill to your local

Skill Files