branchlint

A git branch linter to enforce branch naming convention

Installation

npm

npm install --save-dev branchlint

yarn

yarn add -D branchlint

Add .branchlintrc or .branchlintrc.json like

{
  "allowed": ["master"],
  "disallowed": ["develop", "staging"],
  "prefixes": ["feature", "fix", "hotfix", "release"],
  "separator": "/",
  "maxSections": 2
}

You can customize conventions by override options. The default parameters are

{
  "allowed": [],
  "disallowed": [],
  "prefixes": [],
  "regularExpressions": [],
  "separator": "",
  "maxSections": null,
  "msgPrefixNotAllowed": "Branch name \"%s\" is not allowed.\nAllowed branch name prefix is %s and separator is \"%s\"",
  "msgBranchDisallowed": "Pushing to \"%s\" is not allowed, use GitHub Flow.",
  "msgRegexNotMatched": "Pushing to \"%s\" is not allowed, Allowed regex pattern is \"%s\"",
  "msgSeperatorRequired": "Branch \"%s\" must contain a seperator \"%s\".",
  "msgSectionsOver": "Branch name \"%s\" is not allowed\nAllowed max section length is %s"
}

husky integration

You can use husky a git hook library to check naming convention before push

# npm
npm install --save-dev husky
# yarn
yarn add -D husky

Add husky configuration to package.json or .huskyrc to check branch name.

~
"husky": {
  "hooks": {
      "pre-push": "branchlint"
  }
},

Example Conventions

GitHub Flow convention

{
  "allowed": ["master"],
  "disallowed": ["develop", "staging"],
  "prefixes": ["feature", "fix", "hotfix", "release"],
  "separator": "/",
  "maxSections": 2
}

Git Flow convention

{
  "allowed": ["master", "develop"],
  "disallowed": [],
  "prefixes": ["feature", "fix", "hotfix", "release"],
  "separator": "/",
  "maxSections": 2,
  "msgBranchDisallowed": "Pushing to \"%s\" is not allowed, use git-flow."
}

Usage

Options

option	description
-c, --config	A config file path. Default is .branchlintrc or .brachlintrc.json in current working directory

Configurations

config	description
allowed	An allowed branch names. default: []
disallowed	A disallowed branch names. default: []
prefixes	A required branch name prefixes. default: []
regularExpressions	A regular expressions used for validation. default: []
separator	A separator required for branch name. default: ""
maxSections	Max sections separated by separator parameter. default: null
msgPrefixNotAllowed	The error message when branch name not listed in prefixes is used
msgBranchDisallowed	The error message when disallowed branch name is used
msgRegexNotMatched	The error message when listed regular expressions in regularExpressions
msgSeperatorRequired	The error message when required separator is not found
msgSectionsOver	The error message when section count is bigger than maxSections

Test

Run

yarn test

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

LICENSE

MIT