Registry / devops / branch-name-lint

branch-name-lint

library3.0.1jsnpmunverified

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.

devops testing

npm install branch-name-lint

github ↗package ↗

INSTALL

IMPORT

SIG · BRANCH-NAME-LINT

branch-name-lint

devopsjavascriptv3.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import branchNameLint from 'branch-name-lint'

✗ const branchNameLint = require('branch-name-lint')

Package is ESM-only since v3.0.0; use import. For CommonJS use dynamic import() or stick to v2.x.

branchNameLint

✓ import branchNameLint from 'branch-name-lint'

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

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

types

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

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

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

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); }

branch-name-lint --version

Debug

Known issues

breakingOption 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'.

affects: <2.0.0

breakingBranch 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.

affects: <2.0.0

breakingESM-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.

affects: >=3.0.0

deprecatedNo deprecations known.

affects: all

gotchaConfig 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.

affects: all

Errors

Common errors & fixes

TypeError: branchNameLint is not a function

Using named import instead of default import.

fix

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

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

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().

Invalid branch prefix "Feature"

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.

Upgrade

Version history

3.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/barzik/branch-name-lint ↗

packagehttps://www.npmjs.com/package/branch-name-lint ↗