Git Workflows

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

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

Anti-Pattern 2: Committing Secrets

Anti-Pattern 3: Giant Commits

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:

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