| name | branch-naming-guide |
| description | Invoked automatically when creating git branches to suggest proper names. Covers prefixes: feature/, bugfix/, hotfix/, release/, docs/, test/, chore/, refactor/. Do NOT create branches without following this naming guide. Keywords: branch name, create branch, naming convention, branch prefix, git branch.
|
Git Branch Naming Guide
Format
<prefix>/<kebab-case-description>
Prefix Reference
| Prefix | When to use | Example |
|---|
feature/ | New functionality, user-facing changes | feature/user-auth |
bugfix/ | Non-critical bug fixes | bugfix/fix-login-redirect |
hotfix/ | Urgent production fixes | hotfix/fix-payment-crash |
release/ | Release preparation | release/1.2.0 |
docs/ | Documentation only | docs/update-api-readme |
test/ | Tests only (no feature code) | test/add-auth-coverage |
chore/ | Config, CI, deps, tooling | chore/upgrade-dependencies |
refactor/ | Code restructuring (no behavior change) | refactor/extract-auth-service |
Rules
- Prefix required — always use one of the prefixes above
- Kebab-case — lowercase only, hyphens as separators, no underscores or spaces
- Descriptive — brief but clear (
feature/auth is too short; feature/add-oauth2-google-login is good)
- Max 60 characters (project default, configurable)
- Ticket number — include if required by project config (e.g.,
feature/JIRA-123-add-oauth)
Quick Naming Tips
- Use present tense:
feature/add-login not feature/added-login
- Be specific:
bugfix/fix-null-pointer-in-cart not bugfix/fix-bug
- Skip "the", "a", "an":
feature/user-settings not feature/the-user-settings-page
Good vs Bad Examples
| Bad | Good | Reason |
|---|
my-feature | feature/my-feature | Missing prefix |
Feature/UserAuth | feature/user-auth | Wrong case |
feature/user_auth | feature/user-auth | Underscore → hyphen |
fix | bugfix/fix-login-error | Too vague, missing prefix |
feature/implementing-the-new-very-long-user-authentication-flow-page | feature/user-oauth-login | Too long |
Checking Project Config
If .claude-plugin/git-branch-naming.json exists in the project, it may override:
- Allowed prefixes
- Required ticket pattern (e.g.,
JIRA-\d+, #\d+)
- Max branch name length
- Enforcement mode (
ask vs deny)
Run /git-branch-naming:setup to view or update project configuration.
