new-branch

A composable CLI to generate and create standardized Git branch names using a pattern + transform pipeline.

📖 Full Documentation

---

Install

npx new-branch

Or install globally:

npm install -g new-branch

Quick Start

Bootstrap a .newbranchrc.json config interactively:

npx new-branch init

Or accept all defaults in one shot:

npx new-branch init --yes

Then generate branch names:

npx new-branch \
  --type feat \
  --title "Add login page" \
  --id PROJ-123 \
  --create

✅ Branch created and switched to: feat/add-login-page-PROJ-123

You can also pass a pattern inline:

{
  "pattern": "{type}/{title:slugify}-{id}",
  "types": [
    { "value": "feat", "label": "Feature" },
    { "value": "fix", "label": "Bug Fix" }
  ]
}

Features

• Pattern language — declarative syntax with variables, transforms, and arguments
• 16 built-in transforms — slugify, kebab, camel, max, replace, stripAccents, and more
• Interactive init wizard — new-branch init bootstraps your config with live preview
• Flexible config — .newbranchrc.json, package.json, or git config
• Pattern aliases — define named patterns and switch with --use feature
• Interactive mode — prompts for missing values, disable with --no-prompt
• Git safety — sanitized and validated via git check-ref-format
• Didactic modes — --explain, --list-transforms, --print-config

Documentation

Section	Description
Getting Started	Installation and first branch
Init Wizard	Bootstrap config interactively
Patterns	Pattern language syntax and examples
Transforms	All 16 transforms with I/O tables
Configuration	Config sources and precedence
Pattern Aliases	Named patterns with --use
CLI Reference	All flags and options
Recipes	GitHub Flow, Gitflow, Monorepo

Development

pnpm install
pnpm test:run
pnpm build

License

MIT