# Git Workflow

> Modern Git collaboration patterns for team development - branching strategies, PR workflows, commit conventions, and code review best practices

- Skill: `freddy-chen-ux/git-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add freddy-chen-ux/git-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/freddy-chen-ux/git-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Freddy-CHEN-ux (https://skillmd.com/u/freddy-chen-ux)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/freddy-chen-ux/git-workflow

---


# 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

| Task | Tool/Command | When to Use | Reference |
|------|-------------|-------------|-----------|
| Create feature branch | `git checkout -b feat/name main` | Start new work | [Branching Strategies](resources/branching-strategies.md) |
| Squash WIP commits | `git rebase -i HEAD~3` | Clean up before PR | [Interactive Rebase](resources/interactive-rebase-guide.md) |
| Conventional commit | `git commit -m "feat: add feature"` | All commits | [Commit Conventions](resources/commit-conventions.md) |
| Force push safely | `git push --force-with-lease` | After rebase | [Common Mistakes](resources/common-mistakes.md) |
| Resolve conflicts | `git mergetool` | Merge conflicts | [Conflict Resolution](resources/conflict-resolution.md) |
| Create stacked PRs | `gt create stack-name` (Graphite) | Large features | [Stacked Diffs](resources/stacked-diffs-guide.md) |
| Auto-generate changelog | `npx standard-version` | Before release | [Release Management](resources/release-management.md) |
| Run quality gates | GitHub Actions / GitLab CI | Every PR | [Automated Quality Gates](resources/automated-quality-gates.md) |

---

## Decision Tree: Choosing Branching Strategy

```text
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](resources/branching-strategies.md)** - 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](resources/pr-best-practices.md)** - 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](resources/commit-conventions.md)** - 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](resources/stacked-diffs-guide.md)** - 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](resources/interactive-rebase-guide.md)** - 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](resources/conflict-resolution.md)** - 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](resources/automated-quality-gates.md)** - 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](resources/validation-checklists.md)** - 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](resources/release-management.md)** - 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](resources/common-mistakes.md)** - 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: [templates/pull-requests/pr-template.md](templates/pull-requests/pr-template.md)
Guide: [templates/template-git-workflow-guide.md](templates/template-git-workflow-guide.md)

---

## Security-Sensitive Changes

For security-related git operations, see [git-commit-message/templates/template-security-commits.md](../git-commit-message/templates/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](../software-code-review/SKILL.md) - Code review standards and techniques
- [Quality Debugging](../qa-debugging/SKILL.md) - Git bisect, debugging workflows
- [DevOps Platform Engineering](../ops-devops-platform/SKILL.md) - CI/CD pipelines, automation
- [Software Testing & Automation](../qa-testing-strategy/SKILL.md) - Test-driven development, coverage gates
- [Documentation Standards](../docs-codebase/SKILL.md) - Changelog formats, documentation workflows
- [Git Commit Message](../git-commit-message/SKILL.md) - 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 templates/ for copy-paste ready configurations
- Use resources/ 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**:

```bash
# 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**:

```bash
# 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>
```