Advanced Branch Name Enforcer Enforcer

Validates git branch names against configurable naming conventions, blocking branch creation or pushes that do not conform to the team's branching strategy.

When to Use This Hook

Attach this hook when you need to:

• Enforce a consistent branch naming convention like type/TICKET-123-description
• Prevent ad-hoc branch names that make git history and CI pipelines harder to navigate
• Integrate branch names with issue trackers by requiring ticket IDs in branch names

Consider alternatives when:

• Your team uses trunk-based development with minimal branching
• Branch naming is already enforced by your Git hosting platform's branch policies

Quick Start

Configuration

Copy
name: advanced-branch-name-enforcer-enforcer
type: hook
trigger: PreToolUse
category: git-workflow

Example Trigger

Copy
# Hook triggers before a branch creation or checkout command
git checkout -b feat/PROJ-456-add-dark-mode
# Enforcer validates the branch name against rules

Example Output

Branch Name Enforcer
  Branch: feat/PROJ-456-add-dark-mode
  Pattern: {type}/{ticket}-{description}
  Type: feat ...................... VALID (in: feat, fix, chore, docs, refactor)
  Ticket: PROJ-456 ............... VALID (matches [A-Z]+-\d+)
  Description: add-dark-mode ..... VALID (lowercase kebab-case)
  Length: 28 chars (max: 63) ..... PASS
Branch name approved.

Core Concepts

Naming Convention Overview

Aspect	Details
Type Prefix	feat/, fix/, chore/, docs/, refactor/, hotfix/
Ticket ID	Jira/Linear-style ticket reference (e.g., PROJ-123)
Description	Lowercase kebab-case summary of the work
Separator	Forward slash between type and rest, hyphens within
Max Length	63 characters (git branch name limit for most tools)

Enforcement Workflow

Branch Command Detected
        |
   Extract Branch Name
        |
   Parse Components
        |
   ┌────┼────┬────┐
   |    |    |    |
 Type Ticket Desc Length
   |    |    |    |
   └────┼────┴────┘
        |
   All Valid?
    /       \
  Yes        No
   |          |
 ALLOW     BLOCK +
           Show Pattern
           + Example

Configuration

Parameter	Type	Default	Description
pattern	string	"^(feat|fix|chore|docs|refactor)/[A-Z]+-\\d+-[a-z0-9-]+$"	Regex pattern for valid branch names
allowed_types	string[]	["feat","fix","chore","docs","refactor","hotfix"]	Valid branch type prefixes
require_ticket	boolean	true	Require a ticket ID in the branch name
max_length	number	63	Maximum branch name length
exempt_branches	string[]	["main","master","develop","staging"]	Branches exempt from naming rules

Best Practices

1. Exempt Long-Lived Branches - Always exempt main, master, develop, and staging from naming rules. These branches exist outside the feature branching convention.

2. Keep Descriptions Short but Meaningful - Enforce a maximum description length of 3-5 words in kebab-case. Long branch names are hard to type and display poorly in most git tools.

3. Match Your Issue Tracker - Configure the ticket pattern to match your issue tracker's format. Jira uses PROJ-123, Linear uses TEAM-123, GitHub uses #123. Align the enforcer accordingly.

4. Provide a Branch Name Generator - When the enforcer rejects a name, suggest a corrected version. Transforming "my new feature" into "feat/PROJ-0-my-new-feature" reduces friction.

5. Allow Hotfix Exceptions - Hotfix branches may need expedited creation without a ticket. Allow hotfix/description without requiring a ticket ID for emergency situations.

Common Issues

1. Case Sensitivity on macOS - macOS file systems are case-insensitive, so feat/Add-Feature and feat/add-feature conflict. Enforce lowercase to prevent this issue.

2. Slash Depth Limitations - Some git tools handle nested slashes (feat/auth/login) differently. Limit to a single slash separator unless your tooling supports deeper nesting.

3. Renaming Existing Branches - The enforcer validates at creation time but cannot retroactively fix existing non-conforming branches. Run a one-time audit with git branch -m to rename legacy branches.