home / skills / phrazzld / claude-config / git-mastery

git-mastery skill

safe

This skill helps enforce git workflows and best practices, guiding commits, branches, and merge strategies for reliable, scalable development.

npx playbooks add skill phrazzld/claude-config --skill git-mastery

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

3.4 KB

---
name: git-mastery
user-invocable: false
description: |
  Git workflow enforcement and best practices. Use when:
  - Writing commit messages or reviewing commits
  - Creating branches or choosing merge strategies
  - Setting up CI/CD pipelines with git operations
  - Resolving merge conflicts or rebasing
  - Configuring repository settings or git hooks
  - Optimizing large repository performance
  Keywords: git, commit, branch, merge, rebase, PR, pull request, trunk-based,
  conventional commits, atomic commits, git hooks, CODEOWNERS
effort: high
---

# Git Mastery

Enforce distributed-first, async-friendly git workflows with automated quality gates.

## Commits: Atomic + Conventional

**Every commit must be:**
- Single logical change (use `git add -p` for selective staging)
- Complete (code + tests + docs together)
- Independently buildable and testable
- Describable without "and" in subject

**Format:** `type(scope): subject` (50 chars max)
```
feat(auth): add OAuth2 login flow
fix(api): handle null response in user endpoint
docs(readme): add deployment instructions
refactor(db): extract query builder
```
Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`

BREAKING CHANGE: Add footer `BREAKING CHANGE: description` → triggers MAJOR version.

## Branches: Short-Lived + Typed

**Naming:** `type/issue-description` (lowercase, hyphens, <60 chars)
```
feature/123-oauth-login
fix/456-null-pointer-api
hotfix/critical-auth-bypass
```

**Rules:**
- Max 3 days old (escalate if longer)
- Delete immediately after merge
- Rebase onto main daily: `git pull --rebase origin main`
- Never push directly to main

## Merge Strategy (Algorithmic)

| Condition | Strategy |
|-----------|----------|
| <3 days, single author, atomic | **Rebase** (linear history) |
| Multi-author or external PR | **Merge** (preserve context) |
| Many fixup/experimental commits | **Squash** (clean history) |

Main branch: fast-forward only (`git config merge.ff only`).

## PR Workflow

1. CI passes before human review (lint, type-check, test, security)
2. CODEOWNERS auto-assigns reviewers
3. 1-2 approvals required
4. Squash fixup commits before merge
5. Branch auto-deleted on merge

**Context-rich PRs:** Include motivation, alternatives considered, areas of concern.

## Performance (Large Repos)

Enable commit-graph:
```bash
git config core.commitGraph true
git config gc.writeCommitGraph true
```

Clone optimization:
```bash
git clone --filter=blob:none URL  # Partial clone
git sparse-checkout set src/      # Only needed paths
```

Large files (>10MB): Use Git LFS.

## Anti-Patterns

- Mixed commits ("fix auth and update logging")
- Long-lived branches (>1 week without escalation)
- Manual merge strategy choice (use decision tree)
- Requiring sync coordination across timezones
- Large binary files in git history
- WIP/fix typo commits in main history

## References

- [conflict-resolution.md](references/conflict-resolution.md) - Distributed async conflict patterns
- [feature-flags.md](references/feature-flags.md) - Flag-driven development for long features
- [release-automation.md](references/release-automation.md) - Semantic versioning automation

## Commit Conventions

See `references/commit-conventions.md` for detailed commit message standards including:
- Conventional commit format (type(scope): subject)
- Imperative mood rules
- Body and footer conventions
- Breaking change format

Overview

This skill enforces distributed-first, async-friendly Git workflows and automated quality gates to keep history clean and teams productive. It codifies commit, branch, merge, and PR conventions so changes are atomic, reviewable, and easy to trace. Use it to reduce merge conflicts, improve CI reliability, and scale Git practices across teams.

How this skill works

The skill inspects commit messages, branch names, and PR metadata against defined rules: conventional commit format, atomic commits, short-lived typed branches, and a decision tree for merge strategy. It recommends commands and config snippets (commit-graph, partial clone, sparse-checkout, Git LFS) and guides conflict resolution, rebasing, and branch hygiene. It also enforces CI-first PRs, CODEOWNERS review flow, and fast-forward-only main branch policies.

When to use it

Writing or reviewing commit messages to ensure atomic, conventional commits
Creating branches or picking a merge strategy for a pull request
Setting up CI/CD pipelines that rely on predictable Git history
Resolving merge conflicts, rebasing, or cleaning up fixup commits
Optimizing large repositories with commit-graph, partial clone, or LFS

Best practices

Make each commit a single logical change with code, tests, and docs together
Use conventional commit headers: type(scope): subject (≤50 chars) and imperative mood
Create short-lived typed branches (type/summary), rebase daily onto main, delete after merge
Follow the merge decision tree: rebase for small single-author work, merge for multi-author, squash for cleanup
Require CI to pass before review and enforce 1–2 approvals with CODEOWNERS
Enable commit-graph and use partial clones/sparse-checkout for large repos; use Git LFS for large files

Example use cases

A developer composes a commit: the skill validates the header, checks that tests are present, and suggests splitting if mixed changes are detected
A maintainer reviews a PR and the skill recommends rebasing vs merging based on age, author count, and commit shape
A team onboarding a monorepo uses the clone and sparse-checkout commands to reduce local clone size and speed CI
A release automation pipeline enforces conventional commits and detects BREAKING CHANGE footers to bump major versions
During a conflict, the skill points to distributed async conflict patterns and suggests incremental rebases

FAQ

What constitutes an atomic commit?

An atomic commit contains a single logical change that is independently buildable and testable, includes related tests/docs, and can be described in a short subject without using "and".

When should I rebase versus merge?

Rebase for short-lived (<3 days), single-author, atomic changes to keep a linear history. Merge when multiple authors or preserved context is important. Squash when many small or fixup commits need a clean history.