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

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

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