---

name: git-workflow description: Git worktree workflow, conventional commits, commit trailers, and PR guidelines. Activated during git operations and commits. allowed-tools: ['Bash', 'Read']

Git Workflow Expert

This skill provides guidance on Git worktree workflow, commit standards, and PR best practices.

🌳 Git Worktree Workflow

Why Git Worktree?

Git worktree allows working on multiple branches simultaneously without stashing or switching contexts. Each worktree is an independent working directory with its own branch.

Benefits:

• No context switching between branches
• No stashing required
• Parallel development on different features
• Independent builds and tests per branch

Setting Up Worktrees

# Create worktree for feature development
git worktree add ../project-feature-auth feature/user-authentication

# Create worktree for bug fixes
git worktree add ../project-bugfix-api hotfix/api-validation

# Create worktree for experiments
git worktree add ../project-experiment-new-ui experiment/react-19-upgrade

Worktree Naming Convention

../project-<type>-<description>

Types:

• feature - New feature development
• bugfix - Bug fixes
• hotfix - Urgent production fixes
• experiment - Experimental changes
• refactor - Code refactoring

Examples:

• ../myapp-feature-user-auth
• ../myapp-bugfix-login-error
• ../myapp-hotfix-security-patch

Managing Worktrees

# List all worktrees
git worktree list

# Show details in long format
git worktree list --porcelain

# Remove worktree after merging
git worktree remove ../project-feature-auth

# Remove worktree (force if dirty)
git worktree remove --force ../project-experiment

# Prune stale worktree information
git worktree prune

Worktree Best Practices

1. Clean up after merging - Remove worktrees after feature completion
2. Use descriptive names - Follow naming convention
3. Keep main worktree clean - Use for stable work only
4. Regular pruning - Run git worktree prune periodically

🔧 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

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 or worktree
• [ ] 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/worktree

💡 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 or worktrees
• 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