branch-name-lint

3.0.1 verified Fri May 01 auth: no javascript

A CLI tool to lint and validate Git branch names against configurable rules. Current stable version is 3.0.1, requiring Node.js >=18. It supports prefix whitelisting, separator enforcement, regex patterns, banned/disallowed branch names, and suggestions for common typos. Key differentiators include support for JavaScript config files (for dynamic rules), environment variable override for CI/CD, and the ability to disable prefix or separator checks entirely. Useful for pre-commit hooks (husky) or CI pipelines to enforce branch naming conventions. Last major version (2.0.0) fixed spelling of 'separator' from 'seperator' and made branch names case-sensitive. Release cadence is irregular with maintenance updates.

Common errors

error TypeError: branchNameLint is not a function ↓

cause Using named import instead of default import.

fix

Change to: import branchNameLint from 'branch-name-lint'

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported ↓

cause Using CommonJS require() with v3.x which is ESM-only.

fix

Use import or upgrade Node.js to support ES modules, or use dynamic import().

error Invalid branch prefix "Feature" ↓

cause Case sensitivity change in v2.0.0; prefix in config is lowercase but branch uses uppercase.

fix

Ensure case matches between config prefixes and branch names.

Warnings

breaking Option names changed in v2.0.0: 'seperator' -> 'separator', 'msgseperatorRequiredL' -> 'msgseparatorRequiredL'. Old names cause silent ignore. ↓

fix Update config to use new option names 'separator' and 'msgseparatorRequiredL'.

breaking Branch name and prefix are now case-sensitive in v2.0.0. Previously 'Feature' would match 'feature' prefix. ↓

fix Ensure branch names and config prefixes match case exactly.

breaking ESM-only since v3.0.0. CommonJS require() will fail with ERR_REQUIRE_ESM. ↓

fix Use import or dynamic import(). For CommonJS projects, pin to v2.1.1.

deprecated No deprecations known.

gotcha Config file location as CLI argument is relative to current working directory, not the project root. ↓

fix Use absolute path or ensure correct relative path from cwd.

Install

npm install branch-name-lint

yarn add branch-name-lint

pnpm add branch-name-lint

Imports

default
wrong
```
const branchNameLint = require('branch-name-lint')
```
correct
```
import branchNameLint from 'branch-name-lint'
```
Package is ESM-only since v3.0.0; use import. For CommonJS use dynamic import() or stick to v2.x.

branchNameLint

wrong

import { branchNameLint } from 'branch-name-lint'

correct

import branchNameLint from 'branch-name-lint'

Default export is the lint function; named import will fail.

types

wrong

import { BranchNameLintConfig } from 'branch-name-lint'

correct

import type { BranchNameLintConfig } from 'branch-name-lint'

Type imports require using `import type` in TypeScript; otherwise it will try to import runtime value.

Quickstart

Shows how to import and use branch-name-lint programmatically with a config object.

import branchNameLint from 'branch-name-lint';

const config = {
  prefixes: ['feature', 'hotfix', 'release'],
  separator: '/',
  banned: ['wip'],
  disallowed: ['master', 'develop'],
  suggestions: { feat: 'feature', fix: 'hotfix' },
};

const result = branchNameLint(config, 'feature/my-branch');

if (result.valid) {
  console.log('Branch name is valid!');
} else {
  console.error('Invalid branch name:', result.errors);
}