Git workflow

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 <[email protected]>"

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

# Co-author
git commit --trailer "Co-authored-by: Jane Smith <[email protected]>"

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 <[email protected]>
Reviewed-by: Jane Smith <[email protected]>
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

1. Keep PRs small - Easier to review, faster to merge
2. One feature per PR - Don't mix unrelated changes
3. Update documentation - Keep docs in sync with code
4. Add tests - Don't merge without test coverage
5. Respond to reviews - Address feedback promptly
6. Squash commits - Clean up commit history before merge
7. 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