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:

new-branch init

Or accept all defaults in one shot:

new-branch init --yes

Then generate branch names:

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