git-workflows

name	git-workflows
skill_category	devops
description	Git workflows, branching strategies (gitflow, trunk-based), Conventional Commits, commit message quality, version control best practices, and pull-request conventions — with deterministic convention checker script. Use proactively when reviewing commit message quality before merge, enforcing branch naming conventions, onboarding a team to Conventional Commits, or running a CI hook that validates commits in a PR. Run the checker for deterministic commit and branch convention validation.
version	2.0.0
source	.claude/skills/devops/git-workflows.md (retired flat file); L3 checker added 2026-05-20
when_to_use	["Reviewing commit message quality before merge","Enforcing branch naming conventions in a project","Onboarding a team to Conventional Commits","CI hook that validates commits in a PR"]
allowed-tools	["Bash","Read","Edit","Glob","Grep"]
tags	["git","version-control","branching","commits","workflow","collaboration"]
trigger_files	[".git/config",".gitignore",".gitattributes","CONTRIBUTING.md"]
trigger_keywords	["git","commit","branch","merge","rebase","pull request","PR","version control","gitflow","trunk-based"]

Git Workflows

Best practices for Git version control, branching strategies, and commit conventions. Run the convention checker on commit message batches before merge; use this prose guidance for strategy and workflow decisions (those are judgment calls the script does not make).

Purpose

• Establish consistent Git workflows across projects
• Ensure clean, meaningful commit history
• Prevent common Git mistakes and conflicts
• Facilitate effective code collaboration

---

Commit Message Convention

Use Conventional Commits format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Valid Types

Type	When to Use
feat	New feature for users
fix	Bug fix for users
docs	Documentation only
style	Formatting, no code change
refactor	Code restructuring, no behavior change
perf	Performance improvement
test	Adding/fixing tests
chore	Build, tooling, dependencies
build	Build system changes
ci	CI configuration changes
revert	Reverts a previous commit

Examples

git commit -m "feat(auth): add OAuth2 login support"
git commit -m "fix(api): handle null response from payment service"
git commit -m "feat(api)!: change response format to JSON:API spec"
# Breaking change: add BREAKING CHANGE footer

Why Conventional Commits matter: Enables automated changelogs, semantic versioning, and clear history archaeology. Once committed and merged, a commit message cannot be changed without rewriting history — enforce format before merge, not after.

---

Branching Strategies

Trunk-Based Development (Recommended)

Best for: Teams with strong CI/CD, frequent releases.

main ────●────●────●────●────●────●────
          \        /
           ●──────●  (short-lived feature branch)

Rules:

• Feature branches live < 2 days
• Merge to main frequently
• Use feature flags for incomplete work
• main is always deployable

GitFlow

Best for: Scheduled releases, multiple versions in production.

Branches: main, develop, feature/*, release/*, hotfix/*

Prefer trunk-based for new projects. Only adopt GitFlow when you genuinely maintain multiple production versions simultaneously.

---

Branch Naming Convention

Format: <prefix>/<description-in-kebab-case>

Valid prefixes: feature, feat, fix, hotfix, release, chore, docs, refactor, perf, test, ci, build, spike, experiment, dependabot

Rules:

• All lowercase
• Kebab-case description (hyphens, not underscores or spaces)
• No special characters except - and /
• Protected branches (main, master, develop, staging) are exempt

Examples:

feature/user-authentication
fix/login-null-pointer
hotfix/payment-crash-prod
release/v2-0-0
chore/update-ci-deps

---

Common Workflows

Starting New Feature

git checkout main && git pull --rebase origin main
git checkout -b feature/user-authentication
# work, commit following Conventional Commits
git push -u origin feature/user-authentication

Updating Feature Branch with Main

git fetch origin
git rebase origin/main
# resolve conflicts if any, then:
git push --force-with-lease

---

Anti-Patterns

Anti-Pattern 1: Force Push to Shared Branches

Aspect	Description
WHY	Overwrites others' work. Causes sync issues. Can lose commits.
FIX	Use --force-with-lease on feature branches only. Never force push shared branches.

Anti-Pattern 2: Committing Secrets

Aspect	Description
WHY	Secrets in git history are permanent. Even after removal, they're in history.
FIX	Use .gitignore for .env files. If leaked, rotate credentials immediately.

Anti-Pattern 3: Giant Commits

Aspect	Description
WHY	Hard to review. Difficult to revert. Obscures history.
FIX	Commit early, commit often. One logical change per commit.

---

Invocation — Git Convention Checker (L3 Script)

Run the checker on commit messages and branch names before merge. Consume its output only — the script source never enters context.

What the script checks (deterministic, closed specification):

• GIT-001: Commit messages against Conventional Commits 1.0.0 format + valid type set
• GIT-002: Branch names against <prefix>/<kebab-case-description> convention

What the script does NOT check (prose judgment):

• Whether a branching strategy (trunk-based vs GitFlow) is appropriate for the team
• Whether a commit message is descriptive enough
• Whether commits are atomic or too large
• Rebase vs merge policy

Input format:

{
  "commits": [
    "feat(auth): add OAuth2 login support",
    "fixed the thing"
  ],
  "branches": [
    "feature/user-authentication",
    "FEATURE/Auth"
  ]
}

Either key may be omitted. Empty arrays are valid.

Run via Bash (stdin):

echo '{"commits": ["feat: add login", "bad message"], "branches": ["feature/auth"]}' \
  | python .claude/skills/devops/git-workflows/scripts/git_check.py -

Run via Bash (file argument):

python .claude/skills/devops/git-workflows/scripts/git_check.py input.json

Extract commits from git log for a PR branch:

git log origin/main..HEAD --format="%s" \
  | python3 -c "import sys,json; print(json.dumps({'commits': sys.stdin.read().splitlines()}))" \
  | python .claude/skills/devops/git-workflows/scripts/git_check.py -

Output:

1. JSON object with findings array (each finding has id, severity, item, title, detail, reference) and summary with counts and total commits/branches checked.
2. Markdown findings table.

Findings:

ID	Check	Severity	Source
GIT-001	Non-conventional commit message	HIGH	Conventional Commits 1.0.0
GIT-002	Branch name violates naming convention	MEDIUM	Team branch naming convention

What to do with the output:

1. GIT-001 findings on un-merged commits: request changes before merge. Commit messages are permanent once in shared history.
2. GIT-002 findings: rename the branch before opening a PR (git branch -m old-name new-name).
3. The script exits 0 even with findings — the agent decides what to block on.

Error handling: Exits non-zero on bad JSON, wrong field types, or file not found. Exits 0 for valid input including empty input.

---

Safety Rules

1. Never force push to main/develop — Use --force-with-lease only on feature branches
2. Never commit secrets — Use .gitignore and secret managers
3. Never rewrite shared history — Only rebase unpushed or personal branches
4. Always pull before push — Avoid unnecessary merge conflicts
5. Keep commits atomic — One logical change per commit