Git Workflow (Modern Team Collaboration)

Use modern Git collaboration patterns: GitHub Flow for continuous deploy, trunk-based for scale, Conventional Commits for automation, stacked diffs for large features.

Use this skill to choose a branching model, standardize PR discipline, enforce commit conventions, and harden repository settings for safe collaboration.

Quick Start

• Identify constraints (team size, release cadence, CI maturity, compliance).

• Choose a branching strategy using the decision tree.

• Apply the baseline repo settings (branch protection, approvals, checks, merge strategy).

• Use the relevant reference doc for implementation details.

• If asked "best practice in 2026", verify via web search using data/sources.json as a starting source list.

Quick Reference

Task Tool/Command When to Use Reference

Create feature branch git switch -c feat/name main

Start new work Branching Strategies

Create feature worktree git worktree add ../wt-feature -b feature/name origin/dev

Isolate one feature per branch Branching Strategies

Squash WIP commits git rebase -i HEAD~3

Clean up before PR Interactive Rebase

Conventional commit git commit -m "feat: add feature"

All commits Commit Conventions

Force push safely git push --force-with-lease

After rebase Common Mistakes

Resolve conflicts git mergetool

Merge conflicts Conflict Resolution

Create stacked PRs gt create stack-name (Graphite) Large features Stacked Diffs

Auto-generate changelog npx standard-version

Before release Release Management

Run quality gates GitHub Actions / GitLab CI Every PR Automated Quality Gates

AI Agent Feature Loop

For AI-assisted engineering, prefer this default loop:

• Create one worktree per feature branch.

• Implement scoped changes only for that feature.

• Run repository quality gate(s) before PR.

• Open one focused PR to the integration branch.

If repository scripts exist (for example scripts/git/feature-workflow.sh ), use them to enforce this loop.

Local Safety Preflight (Before Checkout/Merge/Commit)

Use this quick sequence to avoid common local Git blockers during agent-driven work.

• Working tree cleanliness:

• git status --porcelain

• If non-empty, decide explicitly: commit, stash, or abort branch switch.

• Lock/process check:

• If Git commands fail with index.lock , check running Git processes first:

• test -f .git/index.lock && ps aux | rg "[g]it"

• Remove stale lock only after confirming no active Git process.

• Branch switch guard:

• Do not checkout /switch when local changes would be overwritten.

• Commit/stash intentionally; avoid accidental context loss.

• Merge conflict protocol:

• On conflict, stop new edits, resolve conflict file-by-file, rerun relevant tests, then complete merge commit.

• Automation note:

• For recurring branch operations, prefer project scripts/worktrees over ad-hoc local branch juggling.

Decision Tree: Choosing Branching Strategy

Use 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: keep PRs reviewable (often 200-400 LOC works well; split larger changes)

• 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

Monorepo Workflows

Monorepo Workflows - Git patterns for monorepo repositories

• Trunk-based branching for monorepos

• Sparse checkout and partial clone

• Affected-only CI (Nx, Turborepo, Bazel)

• CODEOWNERS per package/directory

• Monorepo vs polyrepo decision table

Git Hooks Automation

Git Hooks Automation - Pre-commit, commit-msg, pre-push hooks

• Husky v9+ and lefthook setup

• lint-staged and commitlint integration

• Custom hooks (gitleaks, file size limits, branch naming)

• Team distribution strategies

Git Bisect Debugging

Git Bisect Debugging - Regression hunting with git bisect

• Manual and automated bisect workflows

• Writing bisect test scripts

• Handling merge commits, log and replay

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

Requirement GitHub Flow Trunk-Based GitFlow

Continuous deployment [OK] Best [OK] Best [FAIL] Poor

Scheduled releases [WARNING] OK [WARNING] OK [OK] Best

Multiple versions [FAIL] Poor [FAIL] Poor [OK] Best

Small team (< 5) [OK] Best [WARNING] OK [FAIL] Overkill

Large team (> 15) [WARNING] OK [OK] Best [WARNING] OK

Fast iteration [OK] Best [OK] Best [FAIL] Poor

PR Size vs Review Time

LOC Review Time Bug Detection Recommendation

< 50 < 10 min High [OK] Ideal for hotfixes

50-200 10-30 min High [OK] Ideal for features

200-400 30-60 min Medium-High [OK] Acceptable

400-1000 1-2 hours Medium [WARNING] Consider splitting

1000 2 hours Low [FAIL] Always split

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

Anti-Pattern Problem Fix

Long-lived branches Merge conflicts, stale code Trunk-based, short branches

Unreviewed merges Bugs reach production Branch protection rules

Rebasing main History corruption Never rebase public branches

1000+ LOC PRs Poor review quality Stacked diffs, split PRs

"fix" commits Unclear history Conventional commits

No CI gates Broken main Required status checks

Secrets in history Security breach Pre-commit hooks, gitleaks

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:

• Start with Quick Reference for fast lookups

• Use Decision Tree for choosing strategies

• Navigate to specific resources for detailed implementation

• Reference templates for production-ready configurations

• Check validation checklists before PR/merge/release

Quick Command Reference

Common Operations:

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 push -m "WIP: implementing feature X" git stash pop

Conflict Resolution:

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, verify current trends via web search (and/or the links in data/sources.json ) 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

• Search: "Git workflow best practices 2026"

• Search: "[specific strategy] vs alternatives 2026"

• Search: "Git collaboration trends January 2026"

• 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