branch-name-lint

Validating and linting the git branch name. Create a config file or use the default configuration file. Use it in husky config file to make sure that your branch will not be rejected by some pesky Jenkins branch name conventions. You may use it as part of a CI process or just as an handy npx command.

Install

$ npm install branch-name-lint

CLI usage

$ npx branch-name-lint

$ npx branch-name-lint --help

  Usage
    npx branch-name-lint [configfileLocation JSON|JS]

  Options
    --help   - to get this screen
    --branch - specify a custom branch name to check instead of the current git branch

  Examples
    $ branch-name-lint
    $ branch-name-lint config-file.json
    $ branch-name-lint config-file.js
    $ branch-name-lint --branch feature/my-new-feature

CLI options.json

Any Valid JSON file with branchNameLinter attribute.

{
    "branchNameLinter": {
        "prefixes": [
            "feature",
            "hotfix",
            "release"
        ],
        "suggestions": {
            "features": "feature",
            "feat": "feature",
            "fix": "hotfix",
            "releases": "release"
        },
        "banned": [
            "wip"
        ],
        "skip": [
            "skip-ci"
        ],
        "disallowed": [
            "master",
            "develop",
            "staging"
        ],
        "separator": "/",
        "branchNameEnvVariable": false,
        "branch": false,
        "msgBranchBanned": "Branches with the name \"%s\" are not allowed.",
        "msgBranchDisallowed": "Pushing to \"%s\" is not allowed, use git-flow.",
        "msgPrefixNotAllowed": "Branch prefix \"%s\" is not allowed.",
        "msgPrefixSuggestion": "Instead of \"%s\" try \"%s\".",
        "msgSeparatorRequired": "Branch \"%s\" must contain a separator \"%s\"."
    }
}

Specifying a Custom Branch Name

You can specify a custom branch name to validate instead of using the current git branch in two ways:

1. Using the CLI flag:

   $ npx branch-name-lint --branch feature/my-custom-branch
   

2. Using configuration:

   1{
   2  "branchNameLinter": {
   3    "branch": "feature/my-custom-branch"
   4  }
   5}

3. Using an environment variable:

   1{
   2  "branchNameLinter": {
   3    "branchNameEnvVariable": "CI_BRANCH_NAME"
   4  }
   5}

   Then set the environment variable:

   CI_BRANCH_NAME=feature/my-custom-branch npx branch-name-lint
   

This is useful for CI/CD environments where you might want to validate branch names from environment variables.

Disabling Checks

You can disable prefix or separator checks by setting their respective configuration values to false:

{
    "branchNameLinter": {
        "prefixes": false,  // Disables the prefix validation check
        "separator": false, // Disables the separator validation check
        "regex": "^(revert|master|develop|issue|release|hotfix/|feature/|support/|shift-)"
    }
}

When prefixes is set to false, any branch prefix will be allowed. When separator is set to false, branches without separators will be allowed.

CLI options.js

You can also use a JavaScript file for configuration, which allows for more dynamic configuration with variables and imports:

1// config-file.js
2// Define constants that can be reused 
3const COMMON_PREFIXES = ['feature', 'bugfix', 'hotfix', 'release'];
4const CI_PREFIXES = ['ci', 'build'];
5
6// Combine arrays for configuration
7const ALL_PREFIXES = [...COMMON_PREFIXES, ...CI_PREFIXES];
8
9// Export the configuration object
10module.exports = {
11  prefixes: ALL_PREFIXES, // Set to false to disable prefix check
12  suggestions: {
13    feat: 'feature'
14  },
15  banned: ['wip', 'tmp'],
16  skip: ['develop', 'master', 'main'],
17  separator: '/', // Set to false to disable separator check
18  disallowed: ['master', 'develop', 'main'],
19  // other options...
20};

Usage with regex

In order to check the branch name with a regex you can add a a regex as a string under the branchNameLinter in your config JSON. You can also pass any options for the regex (e.g. case insensitive: 'i')

{
    "branchNameLinter": {
		"regex": "^([A-Z]+-[0-9]+.{5,70})",
        "regexOptions": "i",
		...
        "msgDoesNotMatchRegex": 'Branch "%s" does not match the allowed pattern: "%s"'
	}
}

Husky usage

After installation, just add in any husky hook as node modules call.

"husky": {
    "hooks": {
        "pre-push": "npx branch-name-lint [sample-configuration.json]"
    }
},

Or with a JavaScript configuration file:

"husky": {
    "hooks": {
        "pre-push": "npx branch-name-lint [sample-configuration.js]"
    }
},

GitHub Actions Usage

You can integrate branch-name-lint into your GitHub Actions workflows to enforce branch naming conventions across your team. This is especially useful for maintaining consistent branch naming in collaborative projects.

Basic Example

Create a workflow file at .github/workflows/branch-name-lint.yml:

1name: Branch Name Lint
2
3on:
4  push:
5    branches-ignore:
6      - main
7      - master
8  pull_request:
9    branches:
10      - main
11      - master
12
13jobs:
14  lint-branch-name:
15    runs-on: ubuntu-latest
16    steps:
17      - uses: actions/checkout@v3
18      - uses: actions/setup-node@v3
19        with:
20          node-version: '18'
21      - run: npm install branch-name-lint --no-save
22      - name: Extract branch name
23        shell: bash
24        run: |
25          if [ "${{ github.event_name }}" == "pull_request" ]; then
26            # For pull requests, use the head branch name
27            echo "BRANCH_NAME=${{ github.head_ref }}" >> $GITHUB_ENV
28          else
29            # For pushes, extract from GITHUB_REF
30            echo "BRANCH_NAME=${GITHUB_REF#refs/heads/}" >> $GITHUB_ENV
31          fi
32      - name: Check branch name
33        run: npx branch-name-lint
34        env:
35          BRANCH_NAME: ${{ env.BRANCH_NAME }}

Advanced Example with Custom Configuration

For more advanced use cases, create a custom configuration file:

1. First, create a config file at .github/branch-name-lint.json:

1{
2  "branchNameLinter": {
3    "prefixes": [
4      "feature",
5      "hotfix",
6      "release",
7      "docs",
8      "chore",
9      "fix",
10      "ci",
11      "test"
12    ],
13    "suggestions": {
14      "features": "feature",
15      "feat": "feature", 
16      "fix": "hotfix", 
17      "releases": "release"
18    },
19    "banned": ["wip"],
20    "skip": ["main", "master", "develop", "staging"],
21    "disallowed": [],
22    "separator": "/",
23    "branchNameEnvVariable": "BRANCH_NAME",
24    "msgBranchBanned": "Branches with the name \"%s\" are not allowed.",
25    "msgPrefixNotAllowed": "Branch prefix \"%s\" is not allowed.",
26    "msgPrefixSuggestion": "Instead of \"%s\" try \"%s\".",
27    "msgSeparatorRequired": "Branch \"%s\" must contain a separator \"%s\"."
28  }
29}

2. Then reference this configuration in your workflow:

1name: Branch Name Lint
2
3on:
4  push:
5    branches-ignore:
6      - main
7      - master
8  pull_request:
9    branches:
10      - main
11      - master
12
13jobs:
14  lint-branch-name:
15    runs-on: ubuntu-latest
16    steps:
17      - uses: actions/checkout@v3
18      - uses: actions/setup-node@v3
19        with:
20          node-version: '18'
21      - run: npm install branch-name-lint --no-save
22      - name: Extract branch name
23        shell: bash
24        run: |
25          if [ "${{ github.event_name }}" == "pull_request" ]; then
26            echo "BRANCH_NAME=${{ github.head_ref }}" >> $GITHUB_ENV
27          else
28            echo "BRANCH_NAME=${GITHUB_REF#refs/heads/}" >> $GITHUB_ENV
29          fi
30      - name: Check branch name
31        run: npx branch-name-lint .github/branch-name-lint.json
32        env:
33          BRANCH_NAME: ${{ env.BRANCH_NAME }}

Handling Different Operating Systems

When using branch-name-lint in a matrix strategy with multiple operating systems, ensure you use environment variables in a cross-platform way:

1jobs:
2  lint-branch-name:
3    runs-on: ${{ matrix.os }}
4    strategy:
5      matrix:
6        os: [ubuntu-latest, windows-latest, macos-latest]
7    steps:
8      - uses: actions/checkout@v3
9      - uses: actions/setup-node@v3
10        with:
11          node-version: '18'
12      - run: npm install branch-name-lint --no-save
13      - name: Extract branch name
14        shell: bash
15        run: |
16          if [ "${{ github.event_name }}" == "pull_request" ]; then
17            echo "BRANCH_NAME=${{ github.head_ref }}" >> $GITHUB_ENV
18          else
19            echo "BRANCH_NAME=${GITHUB_REF#refs/heads/}" >> $GITHUB_ENV
20          fi
21      - name: Check branch name
22        run: npx branch-name-lint .github/branch-name-lint.json
23        env:
24          BRANCH_NAME: ${{ env.BRANCH_NAME }}

This setup ensures that your branch naming conventions are enforced consistently across all contributions to your repository.

Usage in Node.js

1const branchNameLint = require('branch-name-lint');
2
3branchNameLint();
4//=> 1 OR 0.

API

branchNameLint([options])

options

Type: object Default:

{
  prefixes: ['feature', 'hotfix', 'release'],
  suggestions: {features: 'feature', feat: 'feature', fix: 'hotfix', releases: 'release'},
  banned: ['wip'],
  skip: [],
  disallowed: ['master', 'develop', 'staging'],
  separator: '/',
  msgBranchBanned: 'Branches with the name "%s" are not allowed.',
  msgBranchDisallowed: 'Pushing to "%s" is not allowed, use git-flow.',
  msgPrefixNotAllowed: 'Branch prefix "%s" is not allowed.',
  msgPrefixSuggestion: 'Instead of "%s" try "%s".',
  msgSeparatorRequired: 'Branch "%s" must contain a separator "%s".'
}

License

MIT © Ran Bar-Zik