nbranch

Generate meaningful git branch names from task descriptions using NLP.

"Fix the login page crash on mobile" → fix/login-page-crash-mobile
"Add dark mode to dashboard #42"    → feat/dark-mode-dashboard-42
"Refactor Redis caching layer"      → refactor/redis-caching-layer

Install

npm install nbranch
pnpm install nbranch
bun install nbranch
yarn install nbranch

Usage

import { generateBranchName } from "nbranch";

generateBranchName("Fix the login page crash on mobile");
// → "fix/login-page-crash-mobile-a3f1"

generateBranchName("Add OAuth2 support for SSO #123", {
  addRandomSuffix: false,
});
// → "feat/oauth2-sso-123"

Options

import { BranchNameGenerator } from "nbranch";

const generator = new BranchNameGenerator({
  maxLength: 50, // max branch name length (default: 50)
  maxKeywords: 5, // max keywords to extract (default: 5)
  addRandomSuffix: true, // append random 4-char suffix (default: true)
  includeIssueNumber: true, // include #NNN from input (default: true)
  separator: "/", // type/slug separator: "/" or "-" (default: "/")
});

const result = generator.generate("Fix the login bug #891");
// result.name       → "fix/login-bug-891-x7k2"
// result.type       → "fix"
// result.keywords   → ["login", "bug"]
// result.issueNumber → "891"

How it works

The generator runs a 4-stage NLP pipeline:

1. Preprocess — Extracts a clean summary from the input. Handles structured formats (issue titles, markdown headings), strips noise (stack traces, log lines, acceptance criteria), and extracts issue numbers.

2. Analyze — Uses compromise for POS tagging. Detects a conventional commit type (feat, fix, refactor, perf, chore, etc.) from verbs and contextual keywords. Extracts meaningful keywords scored by category: tech terms (react, postgres, oauth2) > domain words (login, cache, endpoint) > nouns > other words.

3. Format — Assembles type/keyword-slug, sanitizes to URL-safe characters, truncates on word boundaries, and optionally appends a random suffix for uniqueness.

4. Output — Returns the branch name along with metadata (type, keywords, issue number).