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:

(): 

[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 /`

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 / 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Everyone-Needs-A-Copilot
• Source: Everyone-Needs-A-Copilot/claude-copilot
• License: MIT
• Homepage: https://ineedacopilot.com

Install and usage instructions live in the source repository linked above.