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 .worktrees/feature -b feature/name`	Isolate one feature per agent/branch	AI Agent Worktrees
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

AI Agent Worktrees Reference — Full guide to worktree isolation for Claude Code, Codex, Aider, and other AI coding agents.

flowchart LR
    A[Plan] --> B[Create worktree<br>per agent/feature]
    B --> C[Verify .gitignore<br>+ install deps]
    C --> D[Agent works<br>scoped commits]
    D --> E[Quality gates]
    E -->|pass| F[PR + merge]
    E -->|fail| D
    F --> G[Cleanup worktree<br>+ delete branch]

    style D fill:#fff3cd,stroke:#d4a017
    style F fill:#d4edda,stroke:#28a745

For AI-assisted engineering, prefer this default loop:

Create one worktree per feature branch (git worktree add .worktrees/<feature> -b feature/<name>).
Verify the worktree directory is in .gitignore (git check-ignore -q .worktrees).
Install dependencies and verify clean test baseline before starting work.
Implement scoped changes only for that feature.
Run repository quality gate(s) before PR.
Open one focused PR to the integration branch.
After merge, clean up: git worktree remove + git branch -d.

Parallel agents: One worktree per agent, disjoint file ownership, orchestrator merges from main. See AI Agent Worktrees for setup, safety patterns, and cleanup.

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: AI Agent Workflows

AI Agent Worktrees

AI Agent Worktrees - Worktree isolation patterns for AI coding agents

When to use worktrees with agents (decision table)
Directory conventions (.worktrees/, global paths, .gitignore)
Agent-specific patterns: Claude Code, Codex, Aider, Copilot Workspace
Parallel agent execution: one worktree per agent, disjoint file ownership
Safety: lock contention, conflict detection, cross-agent file guards
Cleanup lifecycle: removal, pruning, batch cleanup scripts

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 dev-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

Fact-Checking

Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.
Prefer primary sources; report source links and dates for volatile information.
If web access is unavailable, state the limitation and mark guidance as unverified.

dev-git-workflow