---

🚀 Create New Branch

✨ cnb is a simple and customizable CLI tool that helps you create Git branches following naming conventions, and validates (lints) branch names to ensure they follow the configured conventions.

🎬 Demo

📦 Installation

Install the package as a dev dependency:

npm i -D cnb

🛠️ Usage

Creating a New Branch

1. Add the following alias to your .gitconfig:

[alias]
cnb = "!npx cnb"

2. Add the following script to your package.json:

"scripts": {
	"prepare": "git config --local include.path ../.gitconfig",
}

3. Make sure the prepare script runs before trying the new git alias. You can do this by running (only once):

npm i

Or explicitly run the script:

npm run prepare

4. Run the following command to create a new branch with naming conventions:

git cnb

This will prompt you with a set of options to choose from (e.g., feat, fix, chore, etc.). You'll also provide a short description that will be formatted into kebab-case.

Example:

• Selected type: feat
• Description: configure notifications

The branch created will be: feat/configure-notifications.

If your configuration requires a ticket ID (based on your config file), the flow will prompt you to enter that first.

Linting a Branch Name

You can also use cnb to lint and validate if the current branch name follows your configured conventions.

1. Add the following script to your package.json:

"scripts": {
	"cnb:check": "cnb --check"
}

2. Run the script to lint the current branch name:

npm run cnb:check

📁 Configuration

You can customize the behavior of cnb by creating a configuration file in your project root called cnb.config.ts (for ES6 environments) or cnb.config.cjs (for CommonJS environments).

Configuration Options

Option	Type	Description	Default
branchTypes	string[]	The types of branches you can select (e.g., feat, fix, chore, style)	['feat', 'fix', 'chore', 'style']
maxDescriptionLength	number	The maximum length allowed for the branch description.	20
skipTicketId	boolean	Whether to skip the ticket ID prompt.	false
ticketIdPrefix	string	The prefix to add to the ticket ID (e.g., JIRA-).	T-
separator	string	The character(s) used to separate the ticket ID, branch type, and branch name (e.g., /, _).	/

Example cnb.config.ts (ES6)

import type { CnbConfig } from 'cnb';

const config: CnbConfig = {
	branchTypes: ['feat', 'fix', 'chore', 'style'],
	maxDescriptionLength: 20,
	skipTicketId: false,
	ticketIdPrefix: 'JIRA-',
};

export default config;

Example cnb.config.cjs (CommonJS)

module.exports = {
	branchTypes: ['feat', 'fix', 'chore', 'style'],
	maxDescriptionLength: 20,
	skipTicketId: false,
	ticketIdPrefix: 'JIRA-',
};

🛠️ Note for ES6 vs. CommonJS Users

• For ES6 users: Create your configuration file as cnb.config.ts and use export default.
• For CommonJS users: Create your configuration file as cnb.config.cjs and use module.exports.

👥 Authors

📄 License

MIT