branch-name-lint's Introduction

Branch Name Lint

Flexible git branch naming convention checker with some extra validating features

Usage

Globally

> npm install @b12k/branch-name-lint -g
> branch-name-lint

As development dependency

> npm install @b12k/branch-name-lint -D
> npm set-script lint:branch-name "branch-name-lint"

Git hook

Using simple-git-hooks

package.json

{
  "simple-git-hooks": {
    "pre-push": "branch-name-lint"
  }
}

Alternatevly you can use it with husky.

Configuration

Config schema

interface Config {
  pattern: string;
  params: Record<string, string[]>;
  prohibited: string[];
}

User provided configuration

Under the hood BranchNameLint uses cosmicconfig to load its configuration.

You can create one of the following:

branchnamelint property in the package.json file
Extensionless "rc file" in .json or .yaml format
- .branchnamelintrc
"rc file" with .json or .yaml extensions
- .branchnamelintrc.json
- .branchnamelintrc.yaml
"rc file" with .js extension
- .branchnamelintrc.js
".config.js" file
- branchnamelint.config.js

don't forget to do module.exports = {...} in .js config files

BranchNameLint will merge found configuration with its defaults.

Default configuration

module.exports = {
  pattern: ':type/:name',
  params: {
    type: [
      'fix',
      'docs',
      'misc',
      'improve',
      'introduce',
    ],
    name: ['[a-z0-9-]+'],
  },
  prohibited: [
    'ci',
    'wip',
    'main',
    'test',
    'build',
    'master',
    'release',
  ],
};

Linting

BranchNameLint uses path-to-regexp to check if branch name matches the pattern provided in config.

Firstly branch name will be checked if its prohibited or not. On the next step, if params are provided, pattern parts will be modified/populated using respective keys. For example:

(default configuration)
:type/:name => :type(feature|fix|misc|docs)/:name([a-z0-9-]+)

Please refer to path-to-regexp docs for advanced patterns.

Configuration recipes

Only check for protected branches

module.exports = {
  pattern: '', // or other falsy value: undefined | 0 | null | false
  params: {},
  prohibited: [
    'master',
    'main',
    'build',
    'test',
    'wip',
    'ci',
    'release',
  ],
};

Dot-separated username & issue id

b12k.fix/example-branch-description/lbn-12345

module.exports = {
  pattern: ':username.:type/:desc/:issue',
  params: {
    type: [
      'feature',
      'fix',
      'misc',
      'docs',
    ],
    issue: ['lbn-[a-z0-9-]+'],
  },
  prohibited: [
    'master',
    'main',
    'build',
    'test',
    'wip',
    'ci',
    'release',
  ],
};

Scopes for monorepo

feature/my-awesome-app/yet-another-great-feature

(imaginary monorepo structure)
root/
    apps/
        my-awesome-app
        another-great-app
    libs/
        very-useful-lib
        shared-lib
    .branchnamelintrc.js

const fs = require('fs');

const readDirectories = (path) => fs
  .readdirSync(path, { withFileTypes: true })
  .filter((file) => file.isDirectory())
  .map(({ name }) => name);

module.exports = {
  pattern: ':type/:scope/:description',
  params: {
    type: [
      'feature',
      'fix',
      'misc',
      'docs',
    ],
    scope: readDirectories('./apps')
  },
  prohibited: [
    'master',
    'main',
    'build',
    'test',
    'wip',
    'ci',
    'release',
  ],
};

branch-name-lint's People

Contributors

Stargazers

Watchers

branch-name-lint's Issues

Problems running it inside Github Workflow

We found this package that works for validating branch names at the developer workstation via a git hook.

However we also want to enforce the branch name inside a Github Workflow running with the pull_request event.
In that context, the library is not able to successfully get the name of the branch (I think to have found that uses this git command: git rev-parse --abbrev-ref HEAD), getting something like HEAD instead of the name of the branch being merged.

That name comes in the workflow variable github.head_ref but I have not found a way to inject that name into the library.

Can you think of a way that the name of the branch name can be successfully detected in different scenarios/injected via the command line?

Thanks in advance

Allow push to develop and regular branches

If i want to allow push to develop branch, how can i configure the regular expression?.

i'm using

module.exports = {
  pattern: ':type/:user/:month/:name',
  params: {
    type: ['feature', 'fix', 'docs', 'misc', 'improve', 'introduce'],
    user: ['[a-z0-9-]+\\.[a-z0-9-]+'],
    month: ['\\d{4}-\\d{2}'],
    name: ['[a-z0-9-]+']
  },
  prohibited: ['ci', 'wip', 'main', 'test', 'build', 'master', 'release']
};

Thanks

Recommend Projects

b12k / branch-name-lint Goto Github PK