Managing Git Workflows

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