git-branch-naming-setup

name	git-branch-naming-setup
description	Interactive setup wizard for git branch naming conventions. Creates or updates .claude-plugin/git-branch-naming.json with project-specific rules. Run this command to configure prefixes, ticket patterns, enforcement levels, and protected branches. Keywords: setup branch naming, configure conventions, branch config, git naming setup.

Git Branch Naming Setup

Interactive wizard to create or update .claude-plugin/git-branch-naming.json for your project.

What this command does

1. Shows current configuration (if exists)
2. Asks configuration questions via dialog
3. Creates/updates .claude/git-branch-naming.json
4. Optionally installs .githooks/pre-push hook

Setup Steps

Step 1: Check existing config

Read .claude-plugin/git-branch-naming.json if it exists (show current values as defaults). Otherwise use defaults from ${CLAUDE_PLUGIN_ROOT}/templates/git-branch-naming.json.

Step 2: Ask configuration questions

Use AskUserQuestion to collect:

Question 1 — Allowed prefixes (multiSelect):

• feature, bugfix, hotfix, release, docs, test, chore, refactor ← all selected by default
• Allow "Other" to add custom prefixes

Question 2 — Ticket number requirement:

• No ticket required (default)
• JIRA format: [A-Z]+-\d+ (e.g., PROJ-123)
• GitHub issue: #\d+ (e.g., #42)
• Custom pattern (ask for regex)

Question 3 — Max branch name length:

• 60 characters (default)
• 80 characters
• 100 characters
• No limit

Question 4 — Protected branches (multiSelect):

• main, master, develop ← all selected by default

Question 5 — Enforcement level (applies to ALL rules):

• Ask (warn, let user decide) ← default
• Deny (block the command)
• Per-rule (ask for each of: invalid name, protected branch, content mismatch)

Question 6 — Content mismatch detection:

• Enable (warn when branch type doesn't match staged/pushed files) ← default
• Disable

Question 7 — Open PR check (what happens when branch has an open PR by another author):

• Ask (warn, let user decide) ← default
• Deny (block the command)
• Off (skip check entirely)

Question 8 — Install pre-push git hook?:

• Yes, install to .githooks/pre-push (requires git config core.hooksPath .githooks)
• No

Step 3: Write config file

Create .claude-plugin/ directory if needed, then write .claude-plugin/git-branch-naming.json:

{
  "prefixes": ["feature", "bugfix", ...],
  "ticketPattern": "",
  "maxLength": 60,
  "protectedBranches": ["main", "master", "develop"],
  "requireKebabCase": true,
  "warnOnContentMismatch": true,
  "checkOpenPR": "ask",
  "enforcement": {
    "invalidName": "ask",
    "protectedBranch": "ask",
    "contentMismatch": "ask"
  }
}

Step 4: Install pre-push hook (if requested)

Copy ${CLAUDE_PLUGIN_ROOT}/templates/pre-push to .githooks/pre-push, then:

chmod +x .githooks/pre-push
git config core.hooksPath .githooks

Step 5: Show next steps to user

✅ Configuration saved to .claude-plugin/git-branch-naming.json

Next steps:
1. Commit this file: git add .claude-plugin/git-branch-naming.json && git commit -m "chore: add branch naming config"
2. Add plugin to .claude/settings.json: { "enabledPlugins": { "git-branch-naming@artem-from-ua": true } }
3. Push to share conventions with your team

Branch naming enforcement is now active in this Claude Code session.

Config Reference

Field	Type	Default	Description
prefixes	string[]	8 standard prefixes	Allowed branch prefixes
ticketPattern	string	""	Regex for required ticket (empty = not required)
maxLength	number	60	Max branch name length
protectedBranches	string[]	["main","master","develop"]	Branches requiring confirmation to push
requireKebabCase	boolean	true	Enforce kebab-case in description
warnOnContentMismatch	boolean	true	Check files vs branch type on commit/push
checkOpenPR	"ask"|"deny"|"off"	"ask"	What to do when branch has open PR by another author
enforcement.invalidName	"ask"|"deny"	"ask"	What to do when branch name is invalid
enforcement.protectedBranch	"ask"|"deny"	"ask"	What to do when pushing to protected branch
enforcement.contentMismatch	"ask"|"deny"	"ask"	What to do when content doesn't match branch type