---

name: git-workflow description: Modern Git collaboration patterns for team development - branching strategies, PR workflows, commit conventions, and code review best practices metadata: version: "2.0.0" tags: "git, collaboration, code-review, workflow, version-control"

Git Collaboration Workflow — Modern Team Development

Modern Best Practices: GitHub Flow for continuous deployment, Trunk-Based for scale, conventional commits for automation, stacked diffs for large features

This skill provides modern Git collaboration patterns for high-performing engineering teams, covering branching strategies, pull request workflows, commit conventions, code review best practices, and release automation.

---

When to Use This Skill

Invoke this skill when the user asks to:

• Design branching strategies for teams (GitHub Flow, Trunk-Based, GitFlow)
• Create pull request or merge request workflows
• Implement commit conventions (Conventional Commits, semantic versioning)
• Set up code review processes and quality gates
• Resolve merge conflicts or rebase issues
• Configure Git automation (GitHub Actions, GitLab CI PR checks)
• Implement stacked diffs workflows
• Design release management strategies
• Set up automated quality gates in CI/CD
• Create validation checklists for PRs and releases

---

Quick Reference

---

Decision Tree: Choosing Branching Strategy

CopyUse this decision tree to select the optimal branching strategy for your team based on team size, release cadence, and CI/CD maturity.

Team characteristics → What's your situation?
    ├─ Small team (1-5 devs) + Continuous deployment + High CI/CD maturity?
    │   └─ GitHub Flow (main + feature branches)
    │
    ├─ Medium team (5-15 devs) + Continuous deployment + High CI/CD maturity?
    │   └─ Trunk-Based Development (main + short-lived branches)
    │
    ├─ Large team (15+ devs) + Continuous deployment + Very high CI/CD maturity?
    │   └─ Trunk-Based + Feature Flags (progressive rollout)
    │
    ├─ Scheduled releases + Medium CI/CD maturity?
    │   └─ GitFlow (main + develop + release branches)
    │
    └─ Multiple versions + Low-Medium CI/CD maturity?
        └─ GitFlow (long-lived release branches)

---

Navigation: Core Workflows

Branching Strategies

Branching Strategies Comparison - Comprehensive guide to choosing and implementing branching strategies

• GitHub Flow (recommended for modern teams): Simple, continuous deployment
• Trunk-Based Development (enterprise scale): Short-lived branches, daily merges
• GitFlow (structured releases): Scheduled releases, multiple versions
• Decision matrix: Team size, release cadence, CI/CD maturity
• Migration paths between strategies

Pull Request Best Practices

PR Best Practices Guide - Effective code reviews and fast PR cycles

• PR size guidelines: 200-400 lines optimal (46% faster merge)
• Review categories: BLOCKER, WARNING, NITPICK
• Review etiquette: Collaborative feedback, code examples
• PR description templates: What, Why, How, Testing
• Data-driven insights on review efficiency

Commit Conventions

Conventional Commits Standard - Commit message formats and semantic versioning integration

• Conventional commit format: type(scope): description
• Commit types: feat, fix, BREAKING CHANGE, refactor, docs
• SemVer automation: Auto-bump versions from commits
• Changelog generation: Automated from commit history
• Tools: commitlint, semantic-release, standard-version

---

Navigation: Advanced Techniques

Stacked Diffs

Stacked Diffs Implementation - Platform-specific workflows and team adoption

• What are stacked diffs: Break large features into reviewable chunks
• When to use: Features > 500 lines, complex refactoring
• GitLab native support: MR chains
• GitHub with Graphite: CLI-based stacking
• Benefits: 60% faster review cycles, better quality

Interactive Rebase

Interactive Rebase & History Cleanup - Maintain clean commit history

• Auto-squash workflow: fixup! and squash! commits
• Interactive rebase commands: pick, reword, edit, squash, fixup, drop
• Splitting commits: Break large commits into focused changes
• Reordering commits: Logical commit history
• Best practices: Never rebase public branches

Conflict Resolution

Conflict Resolution Techniques - Merge strategies and conflict handling

• Resolution strategies: --ours, --theirs, manual merge
• Rebase vs merge: When to use each
• Merge tool setup: VS Code, Meld, custom tools
• Conflict markers: Understanding <<<<<<<, =======, >>>>>>>
• Prevention strategies: Frequent rebasing, small PRs

---

Navigation: Automation & Quality

Automated Quality Gates

Automated Quality Gates - CI/CD pipelines and quality enforcement

• Essential gates: Tests, coverage, linting, security scans
• Advanced gates: Performance benchmarks, bundle size, a11y checks
• GitHub Actions workflows: Complete PR checks pipeline
• GitLab CI pipelines: MR quality gates
• Pre-commit hooks: Husky + lint-staged setup
• Quality metrics thresholds: Coverage 80%, complexity < 10

Validation Checklists

Validation Checklists - Pre-PR, pre-merge, pre-release checklists

• Before creating PR: Code quality, commit hygiene, testing
• Before merging PR: Review process, CI/CD checks, final verification
• Before releasing: Pre-release testing, version management, documentation
• Post-deployment: Immediate verification, monitoring, tasks
• Hotfix checklist: Critical bug fast-track process

Release Management

Release Management - Versioning and deployment workflows

• Semantic versioning: MAJOR.MINOR.PATCH
• Manual release workflow: GitFlow release branches
• Automated releases: semantic-release automation
• Hotfix workflow: Emergency patches
• Changelog generation: Keep a Changelog format
• Release checklists: Pre-release, release day, post-release

---

Navigation: Learning & Troubleshooting

Common Mistakes

Common Mistakes & Fixes - Learn from common pitfalls

• Large unfocused PRs → Split into stacked diffs
• Vague commit messages → Use conventional commits
• Rewriting public history → Never rebase main
• Ignoring review comments → Address all feedback
• Committing secrets → Use environment variables
• Force push dangers → Use --force-with-lease

---

Decision Tables

When to Use Each Branching Strategy

PR Size vs Review Time

---

Do / Avoid

GOOD: Do

• Keep PRs under 400 lines (200-400 optimal)
• Use conventional commit messages
• Rebase before opening PR (clean history)
• Require at least one approval before merge
• Run CI checks on every PR
• Use stacked diffs for large features (>500 LOC)
• Squash WIP commits before merge
• Use --force-with-lease (not --force)

BAD: Avoid

• Long-lived feature branches (>3 days)
• Merging without review
• Rebasing public/shared branches
• Force pushing to main/master
• Committing secrets (even "temporarily")
• Large monolithic PRs (>1000 lines)
• Vague commit messages ("fix", "update")
• Skipping CI to merge faster

---

Anti-Patterns

---

Repository Baseline (Security + Reliability)

Set these repo defaults before scaling a team:

• Branch protection: require PRs to main (no direct pushes), require status checks, require up-to-date branch on merge.
• Review gates: require approvals; enforce CODEOWNERS for sensitive paths (auth, payments, infra, prod configs).
• History policy: pick merge strategy (squash vs merge commits) and make it consistent; document exceptions.
• Signed changes: require signed commits and signed tags for releases (team-specific key management).
• Secret prevention: local pre-commit + server-side secret scanning/push protection; rotate on incident.
• Merge safety: use merge queue (or equivalent) for busy repos to keep main green under high concurrency.
• Cost control: cache dependencies/builds; run heavy jobs conditionally; cap CI minutes for untrusted forks.

Template: assets/pull-requests/pr-template.md Guide: assets/template-git-workflow-guide.md

---

Security-Sensitive Changes

For security-related git operations, see git-commit-message/assets/template-security-commits.md:

• Secrets detection with pre-commit hooks
• Handling accidental secret commits
• Security commit metadata (CVE, CVSS)
• Branch protection for security-sensitive code

---

Optional: AI/Automation

Note: AI tools assist but cannot replace human judgment for merge decisions.

• PR summarization — Generate description from commits
• Change risk labeling — Flag high-risk files (auth, payments)
• Review suggestions — Identify potential reviewers

Bounded Claims

• AI summaries need human verification
• Risk labels are suggestions, not guarantees
• Merge decisions always require human approval

---

Related Skills

• Software Code Review - Code review standards and techniques
• Quality Debugging - Git bisect, debugging workflows
• DevOps Platform Engineering - CI/CD pipelines, automation
• Software Testing & Automation - Test-driven development, coverage gates
• Documentation Standards - Changelog formats, documentation workflows
• Git Commit Message - Commit message conventions, security commits

---

Usage Notes

For Claude Code:

• Recommend GitHub Flow for most modern teams (simple, effective)
• Suggest stacked diffs for features > 500 lines
• Always validate commit messages against conventional commit format
• Check PR size - warn if > 400 lines, block if > 1000 lines
• Reference assets/ for copy-paste ready configurations
• Use references/ for deep-dive implementation guidance

Progressive Disclosure:

1. Start with Quick Reference for fast lookups
2. Use Decision Tree for choosing strategies
3. Navigate to specific resources for detailed implementation
4. Reference templates for production-ready configurations
5. Check validation checklists before PR/merge/release

---

Quick Command Reference

Common Operations:

Copy# Rebase feature branch
git fetch origin && git rebase origin/main

# Interactive rebase last 3 commits
git rebase -i HEAD~3

# Squash all commits in branch
git rebase -i $(git merge-base HEAD main)

# Force push safely
git push --force-with-lease origin feature-branch

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Cherry-pick specific commit
git cherry-pick abc123

# Stash changes
git stash save "WIP: implementing feature X"
git stash pop

Conflict Resolution:

Copy# Pull latest with rebase
git pull --rebase origin main

# Use visual merge tool
git mergetool

# Accept their changes
git checkout --theirs <file>

# Accept your changes
git checkout --ours <file>

---

Trend Awareness Protocol

IMPORTANT: When users ask recommendation questions about Git workflows, branching strategies, or collaboration tools, you MUST use WebSearch to check current trends before answering.

Trigger Conditions

• "What's the best Git workflow for [team size/use case]?"
• "What should I use for [branching/PR management]?"
• "What's the latest in Git collaboration?"
• "Current best practices for [branching/code review]?"
• "Is [GitFlow/Trunk-Based] still relevant in 2026?"
• "[GitHub Flow] vs [Trunk-Based] vs [GitFlow]?"
• "Best PR stacking tool?"

Required Searches

1. Search: "Git workflow best practices 2026"
2. Search: "[specific strategy] vs alternatives 2026"
3. Search: "Git collaboration trends January 2026"
4. Search: "[branching/PR tools] comparison 2026"

What to Report

After searching, provide:

• Current landscape: What Git workflows/tools are popular NOW
• Emerging trends: New collaboration patterns, tools, or practices gaining traction
• Deprecated/declining: Strategies/tools losing relevance or support
• Recommendation: Based on fresh data, not just static knowledge

Example Topics (verify with fresh search)

• Branching strategies (Trunk-Based, GitHub Flow, GitFlow)
• PR stacking tools (Graphite, git-stack, Stacked PRs)
• Merge queue implementations (GitHub, GitLab)
• Code review platforms and automation
• Conventional commits and changelog tools
• Git hosting platform features (GitHub, GitLab, Bitbucket)
• AI-assisted Git workflows