Branch Naming

Branches in this monorepo follow a strict <type>/<kebab-case-description> shape. The check runs on git push: if the branch you are pushing does not match the pattern, the push is rejected before it ever touches the remote.

The pattern

1
<type>/<kebab-case-description>

• type — one of the allowed prefixes below. Same list that commitlint uses for commit types, minus the ones that never make sense for a branch (style, perf, build, revert).
• description — lower-case letters and digits, separated by hyphens. No spaces, no underscores, no slashes, no camelCase. Must start with a letter or digit.

The exact regex enforced by the hook is:

1
^(feat|fix|chore|ci|docs|refactor|test|variant)\/[a-z0-9][a-z0-9-]*$

Allowed type prefixes

Why the convention exists

Branch naming is not bureaucracy for its own sake — the pattern unlocks several things:

• Predictable automation hooks. CI jobs can key off the prefix: docs/* branches skip the full test matrix, ci/* branches trigger a self-check, feat/* branches run the full suite. Without a convention, every workflow would need a manually maintained list.
• CI routing and triage. When a branch fails on CI, the prefix tells the on-call reviewer what kind of change they are looking at before they open the diff. A red chore/update-deps is triaged differently than a red fix/search-url-html-strip.
• Human readability in the branch list. git branch -a is easier to scan when every branch starts with a verb-sized prefix. You can find "all the doc branches" at a glance.
• Consistency with commit types. Using the same vocabulary for branches and commits means a single mental model — not two.
• Kebab-case is URL-safe. Branch names end up in GitHub URLs, CI job names, and Slack notifications. Hyphens render cleanly everywhere; underscores and camelCase do not.

Passing examples

1
feat/documentation-website
2
feat/add-playground-controls
3
fix/search-url-html-strip
4
fix/button-hover-state
5
docs/contributor-workflow
6
chore/update-deps
7
variant/links-grid-compact
8
refactor/extract-cva-factory
9
test/datatable-sort-order
10
ci/add-a11y-workflow

All of these match the pattern: allowed prefix, slash, kebab-case description starting with a letter or digit.

Failing examples

Each failure below is the actual error message the hook prints before exit 1. The message comes straight from .husky/pre-push.

Wrong prefix

1
feature/add-playground-controls

1
ERROR: Branch name 'feature/add-playground-controls' does not match the naming convention.
2
 
3
  Pattern: <type>/<kebab-case-description>
4
  Types:   feat, fix, chore, ci, docs, refactor, test, variant
5
 
6
  Examples:
7
    feat/documentation-website
8
    fix/button-hover-state
9
    variant/links-grid-compact
10
    chore/update-deps

feature is not in the allowed list — use feat instead.

No slash

1
feat-add-playground-controls

1
ERROR: Branch name 'feat-add-playground-controls' does not match the naming convention.
2
 
3
  Pattern: <type>/<kebab-case-description>
4
  Types:   feat, fix, chore, ci, docs, refactor, test, variant
5
 
6
  Examples:
7
    feat/documentation-website
8
    fix/button-hover-state
9
    variant/links-grid-compact
10
    chore/update-deps

The type and the description have to be separated by a slash, not a hyphen.

Upper-case or camelCase description

1
feat/AddPlaygroundControls

1
ERROR: Branch name 'feat/AddPlaygroundControls' does not match the naming convention.
2
 
3
  Pattern: <type>/<kebab-case-description>
4
  Types:   feat, fix, chore, ci, docs, refactor, test, variant
5
 
6
  Examples:
7
    feat/documentation-website
8
    fix/button-hover-state
9
    variant/links-grid-compact
10
    chore/update-deps

Descriptions must be kebab-case — lower-case, hyphen-separated.

Underscores instead of hyphens

1
feat/add_playground_controls

1
ERROR: Branch name 'feat/add_playground_controls' does not match the naming convention.
2
 
3
  Pattern: <type>/<kebab-case-description>
4
  Types:   feat, fix, chore, ci, docs, refactor, test, variant
5
 
6
  Examples:
7
    feat/documentation-website
8
    fix/button-hover-state
9
    variant/links-grid-compact
10
    chore/update-deps

Underscores are not allowed — use hyphens.

Exempt branches

A handful of branch names bypass the check entirely. The hook uses a case statement against the current branch and ;; skips validation when the branch matches any of these patterns:

The exempt list is deliberately small. Everything else — including personal scratch branches, WIP spikes, and experiments — has to follow the convention.

When the hook runs

The check is part of .husky/pre-push, which fires every time you run git push. If you have never pushed a branch before, the hook runs once the branch is named and tracked — you do not need a remote to trigger it locally during git push.

If you realise mid-work that your branch is misnamed, rename it before pushing:

1
git branch -m old-name feat/new-name

Related

• Commit messages — the sibling convention that commitlint enforces on every commit.
• Git hooks — the full tour of husky hooks, including what pre-push does after the branch check passes.