# Git Conventions

> Apply when committing, branching, or opening a pull request. Conventional commit format, branch naming, PR scope.

- Skill: `sordi-ai/git-conventions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sordi-ai/git-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sordi-ai/git-conventions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: sordi-ai (https://skillmd.com/u/sordi-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sordi-ai/git-conventions

---


# Sub-Skill: Git & Workflow Conventions
<!-- target: ~650 tokens (real tiktoken count) | 15 rules -->

**Purpose:** Consistent commit history, clean branches, no merge conflicts through discipline.
Rules that work in teams of 2–20 developers.

---

## Rules

### Commit Messages (Conventional Commits)

1. **Format:** `<type>(<scope>): <description>` — always lowercase, no period at the end.
   - Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`, `ci`
   - Example: `feat(auth): add JWT refresh token rotation`
2. **Description in imperative mood.** `add feature` not `added feature` or `adds feature`.
3. **Scope is the affected module name.** `fix(user-service): handle null email` — not `fix(backend)`.
4. **Mark breaking changes with `!`.** `feat(api)!: remove deprecated v1 endpoints`
5. **Body for non-obvious changes.** Explains the *why*, not the *what*.

### Branching

6. **Branch names:** `<type>/<ticket-id>-<short-description>` — e.g. `feat/PROJ-123-user-export`.
7. **Feature branches live max. 2 days.** Longer → rebase daily onto `main`.
8. **No direct push to `main` or `develop`.** Always through a pull request.
9. **Delete branch before PR merge.** Clean up merged branches from remote.

### Pull Requests

10. **PR title = commit message of the squash commit.** Consistency between PR and git log.
11. **Max. 400 lines diff per PR.** Larger → split. Reviewers cannot meaningfully review more than 400 lines.
12. **Self-review before opening a PR.** Read through once yourself, fix obvious mistakes.

### Merge Strategy

13. **Squash-merge for feature branches.** Clean linear history on `main`.
14. **Merge commit for release branches.** So release points remain visible.
15. **`git rebase -i` before PR for clean commits.** Squash WIP commits together.

---

## Why This Sub-Skill Earns Stars

The agent automatically creates correct commit messages and branch names.
No manual corrections, no discussions in review about formatting.