/managing-git-workflows

name: managing-git-workflows
description: Manage Git branching strategies, commit conventions, and collaboration workflows. Use when choosing between trunk-based development, GitHub Flow, or GitFlow, implementing conventional commits for automated versioning, setting up Git hooks for quality gates, or organizing monorepos with clear ownership.

Git Workflows

Implement structured Git workflows for team collaboration, code quality, and automated releases. This skill covers branching strategies, conventional commit formats, Git hooks, and monorepo management patterns.

When to Use This Skill

Use this skill when:

• Choosing a branching strategy for a new project or team
• Implementing consistent commit message formats
• Setting up Git hooks for linting, testing, or validation
• Managing monorepos with multiple projects
• Establishing code review workflows
• Automating versioning and releases

Quick Decision: Which Branching Strategy?

Trunk-Based Development

Use when the team has strong CI/CD automation, comprehensive test coverage (80%+), and deploys frequently (daily or more). Short-lived branches merge within 1 day. Requires feature flags for incomplete features.

**Best for:** High-velocity teams with mature DevOps practices (Google, Facebook, Netflix)

GitHub Flow

Use for web applications with continuous deployment. Main branch always represents production. Simple PR-based workflow for small to medium teams (2-20 developers).

**Best for:** Startups, SaaS products, open-source projects

GitFlow

Use when supporting multiple production versions simultaneously, requiring formal QA cycles, or following scheduled releases (monthly, quarterly). More complex but structured.

**Best for:** Enterprise software, mobile apps with App Store releases, on-premise products

For detailed branching patterns with examples, see `references/branching-strategies.md`.

Conventional Commits

Structure commit messages for automated versioning and changelog generation:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

**Common Types:**

• `feat` - New feature (MINOR version bump: 0.1.0)
• `fix` - Bug fix (PATCH version bump: 0.0.1)
• `docs` - Documentation only
• `refactor` - Code restructuring without feature change
• `test` - Adding or updating tests
• `chore` - Maintenance tasks

**Breaking Changes:**

• Add `!` after type: `feat!:` or `fix!:`
• Add `BREAKING CHANGE:` in footer
• Results in MAJOR version bump (1.0.0)

**Examples:**

git commit -m "feat(auth): add JWT token validation"
git commit -m "fix: resolve race condition in user login"
git commit -m "feat!: redesign authentication API

BREAKING CHANGE: Auth endpoints now require API version header"

For complete specification and tooling setup, see `references/conventional-commits.md`.

Git Hooks for Quality Gates

Automate code quality checks at key workflow points:

**pre-commit** - Run before commit is created

• Linting (ESLint, Prettier)
• Formatting checks
• Quick tests

**commit-msg** - Validate commit message format

• Enforce conventional commits
• Check message length

**pre-push** - Run before pushing to remote

• Full test suite
• Prevent force push to protected branches

**Quick Setup with Husky:**

npm install --save-dev husky lint-staged @commitlint/cli @commitlint/config-conventional
npx husky init
npx husky add .husky/pre-commit "npx lint-staged"
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'

For complete hook configuration and examples, see `references/git-hooks-guide.md`.

Monorepo Management

Build Tool Selection

**Nx** - Best for TypeScript/JavaScript monorepos

• Dependency graph analysis
• Affected commands (only rebuild changed projects)
• Distributed caching

**Turborepo** - Best for Next.js/React applications

• Fast incremental builds
• Remote caching
• Simple configuration

**Sparse Checkout** - For large repos when full clone not needed

git sparse-checkout init --cone
git sparse-checkout set apps/web libs/ui-components

Code Ownership

Use `.github/CODEOWNERS` to define ownership:

# Default owners
* @org/engineering

# Apps ownership
/apps/web/ @org/web-team
/apps/mobile/ @org/mobile-team

# Security-critical
/libs/auth/ @org/security-team @org/principal-engineers

For detailed monorepo patterns, see `references/monorepo-patterns.md`.

Merge vs Rebase

Merge Commits

Use when preserving complete history is important:

git checkout main
git merge feature-branch

**When:** Multiple developers on feature branch, want to see integration point

Squash and Merge

Use for clean, linear history:

git checkout main
git merge --squash feature-branch
git commit -m "feat: add user authentication"

**When:** Feature has many WIP commits, want clean main branch history

Rebase

Use for linear history without merge commits:

git checkout feature-branch
git rebase main

**When:** Updating feature branch, working alone, cleaning up before PR

**⚠️ Never rebase:** Public branches (main, develop) or commits already pushed and used by others

Code Review Workflows

Pull Request Template

Create `.github/PULL_REQUEST_TEMPLATE.md`:

## Description
<!-- Brief description of changes -->

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-reviewed code
- [ ] Added tests
- [ ] Updated documentation
- [ ] Tests pass locally

Branch Protection Rules

Enforce quality gates via repository settings:

• Require pull request reviews (2+ approvals)
• Require status checks (build, tests, lint)
• Require branches up to date before merging
• Restrict force pushes and deletions

For complete code review setup, see `references/code-review-workflows.md`.

Branch Naming Conventions

Use consistent naming for clarity:

• `feature/user-authentication` -