{"id":13627460,"url":"https://github.com/barzik/branch-name-lint","last_synced_at":"2025-09-19T12:42:50.736Z","repository":{"id":25706273,"uuid":"106296638","full_name":"barzik/branch-name-lint","owner":"barzik","description":"Lint your branch names","archived":false,"fork":false,"pushed_at":"2024-07-23T10:47:15.000Z","size":291,"stargazers_count":88,"open_issues_count":12,"forks_count":21,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-16T16:13:09.272Z","etag":null,"topics":["branch","continuous-integration","git","linter"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/barzik.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-10-09T14:48:43.000Z","updated_at":"2025-03-05T07:35:10.000Z","dependencies_parsed_at":"2024-01-29T09:18:41.908Z","dependency_job_id":"64ad0012-f4f7-4cf2-8b76-884fc1cacb79","html_url":"https://github.com/barzik/branch-name-lint","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barzik%2Fbranch-name-lint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barzik%2Fbranch-name-lint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barzik%2Fbranch-name-lint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barzik%2Fbranch-name-lint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/barzik","download_url":"https://codeload.github.com/barzik/branch-name-lint/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249280674,"owners_count":21243142,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["branch","continuous-integration","git","linter"],"created_at":"2024-08-01T22:00:34.313Z","updated_at":"2025-09-19T12:42:50.707Z","avatar_url":"https://github.com/barzik.png","language":"JavaScript","funding_links":[],"categories":["Projects by main language"],"sub_categories":["javascript"],"readme":"# branch-name-lint ![Build Status](https://github.com/barzik/branch-name-lint/workflows/Branch%20Lint%20Name%20CI/badge.svg) [![Known Vulnerabilities](https://snyk.io/test/github/barzik/branch-name-lint/badge.svg)](https://snyk.io/test/github/barzik//branch-name-lint) ![npm](https://img.shields.io/npm/dt/branch-name-lint)\n\nValidating 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.\n\n## Install\n\n```\n$ npm install branch-name-lint\n```\n\n## CLI usage\n\n```\n$ npx branch-name-lint\n```\n\n```\n$ npx branch-name-lint --help\n\n  Usage\n    npx branch-name-lint [configfileLocation JSON|JS]\n\n  Options\n    --help   - to get this screen\n    --branch - specify a custom branch name to check instead of the current git branch\n\n  Examples\n    $ branch-name-lint\n    $ branch-name-lint config-file.json\n    $ branch-name-lint config-file.js\n    $ branch-name-lint --branch feature/my-new-feature\n```\n\n### CLI options.json\n\nAny Valid JSON file with `branchNameLinter` attribute.\n\n```\n{\n    \"branchNameLinter\": {\n        \"prefixes\": [\n            \"feature\",\n            \"hotfix\",\n            \"release\"\n        ],\n        \"suggestions\": {\n            \"features\": \"feature\",\n            \"feat\": \"feature\",\n            \"fix\": \"hotfix\",\n            \"releases\": \"release\"\n        },\n        \"banned\": [\n            \"wip\"\n        ],\n        \"skip\": [\n            \"skip-ci\"\n        ],\n        \"disallowed\": [\n            \"master\",\n            \"develop\",\n            \"staging\"\n        ],\n        \"separator\": \"/\",\n        \"branchNameEnvVariable\": false,\n        \"branch\": false,\n        \"msgBranchBanned\": \"Branches with the name \\\"%s\\\" are not allowed.\",\n        \"msgBranchDisallowed\": \"Pushing to \\\"%s\\\" is not allowed, use git-flow.\",\n        \"msgPrefixNotAllowed\": \"Branch prefix \\\"%s\\\" is not allowed.\",\n        \"msgPrefixSuggestion\": \"Instead of \\\"%s\\\" try \\\"%s\\\".\",\n        \"msgSeparatorRequired\": \"Branch \\\"%s\\\" must contain a separator \\\"%s\\\".\"\n    }\n}\n```\n\n### Specifying a Custom Branch Name\n\nYou can specify a custom branch name to validate instead of using the current git branch in two ways:\n\n1. Using the CLI flag:\n   ```\n   $ npx branch-name-lint --branch feature/my-custom-branch\n   ```\n\n2. Using configuration:\n   ```json\n   {\n     \"branchNameLinter\": {\n       \"branch\": \"feature/my-custom-branch\"\n     }\n   }\n   ```\n\n3. Using an environment variable:\n   ```json\n   {\n     \"branchNameLinter\": {\n       \"branchNameEnvVariable\": \"CI_BRANCH_NAME\"\n     }\n   }\n   ```\n\n   Then set the environment variable:\n   ```\n   CI_BRANCH_NAME=feature/my-custom-branch npx branch-name-lint\n   ```\n\nThis is useful for CI/CD environments where you might want to validate branch names from environment variables.\n\n### Disabling Checks\n\nYou can disable prefix or separator checks by setting their respective configuration values to `false`:\n\n```\n{\n    \"branchNameLinter\": {\n        \"prefixes\": false,  // Disables the prefix validation check\n        \"separator\": false, // Disables the separator validation check\n        \"regex\": \"^(revert|master|develop|issue|release|hotfix/|feature/|support/|shift-)\"\n    }\n}\n```\n\nWhen `prefixes` is set to `false`, any branch prefix will be allowed. When `separator` is set to `false`, branches without separators will be allowed.\n\n### CLI options.js\n\nYou can also use a JavaScript file for configuration, which allows for more dynamic configuration with variables and imports:\n\n```js\n// config-file.js\n// Define constants that can be reused \nconst COMMON_PREFIXES = ['feature', 'bugfix', 'hotfix', 'release'];\nconst CI_PREFIXES = ['ci', 'build'];\n\n// Combine arrays for configuration\nconst ALL_PREFIXES = [...COMMON_PREFIXES, ...CI_PREFIXES];\n\n// Export the configuration object\nmodule.exports = {\n  prefixes: ALL_PREFIXES, // Set to false to disable prefix check\n  suggestions: {\n    feat: 'feature'\n  },\n  banned: ['wip', 'tmp'],\n  skip: ['develop', 'master', 'main'],\n  separator: '/', // Set to false to disable separator check\n  disallowed: ['master', 'develop', 'main'],\n  // other options...\n};\n```\n\n## Usage with regex\n\nIn 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')\n\n```\n{\n    \"branchNameLinter\": {\n\t\t\"regex\": \"^([A-Z]+-[0-9]+.{5,70})\",\n        \"regexOptions\": \"i\",\n\t\t...\n        \"msgDoesNotMatchRegex\": 'Branch \"%s\" does not match the allowed pattern: \"%s\"'\n\t}\n}\n```\n\n## Husky usage\n\nAfter installation, just add in any husky hook as node modules call.\n\n```\n\"husky\": {\n    \"hooks\": {\n        \"pre-push\": \"npx branch-name-lint [sample-configuration.json]\"\n    }\n},\n```\n\nOr with a JavaScript configuration file:\n\n```\n\"husky\": {\n    \"hooks\": {\n        \"pre-push\": \"npx branch-name-lint [sample-configuration.js]\"\n    }\n},\n```\n\n## GitHub Actions Usage\n\nYou 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.\n\n### Basic Example\n\nCreate a workflow file at `.github/workflows/branch-name-lint.yml`:\n\n```yaml\nname: Branch Name Lint\n\non:\n  push:\n    branches-ignore:\n      - main\n      - master\n  pull_request:\n    branches:\n      - main\n      - master\n\njobs:\n  lint-branch-name:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: actions/setup-node@v3\n        with:\n          node-version: '18'\n      - run: npm install branch-name-lint --no-save\n      - name: Extract branch name\n        shell: bash\n        run: |\n          if [ \"${{ github.event_name }}\" == \"pull_request\" ]; then\n            # For pull requests, use the head branch name\n            echo \"BRANCH_NAME=${{ github.head_ref }}\" \u003e\u003e $GITHUB_ENV\n          else\n            # For pushes, extract from GITHUB_REF\n            echo \"BRANCH_NAME=${GITHUB_REF#refs/heads/}\" \u003e\u003e $GITHUB_ENV\n          fi\n      - name: Check branch name\n        run: npx branch-name-lint\n        env:\n          BRANCH_NAME: ${{ env.BRANCH_NAME }}\n```\n\n### Advanced Example with Custom Configuration\n\nFor more advanced use cases, create a custom configuration file:\n\n1. First, create a config file at `.github/branch-name-lint.json`:\n\n```json\n{\n  \"branchNameLinter\": {\n    \"prefixes\": [\n      \"feature\",\n      \"hotfix\",\n      \"release\",\n      \"docs\",\n      \"chore\",\n      \"fix\",\n      \"ci\",\n      \"test\"\n    ],\n    \"suggestions\": {\n      \"features\": \"feature\",\n      \"feat\": \"feature\", \n      \"fix\": \"hotfix\", \n      \"releases\": \"release\"\n    },\n    \"banned\": [\"wip\"],\n    \"skip\": [\"main\", \"master\", \"develop\", \"staging\"],\n    \"disallowed\": [],\n    \"separator\": \"/\",\n    \"branchNameEnvVariable\": \"BRANCH_NAME\",\n    \"msgBranchBanned\": \"Branches with the name \\\"%s\\\" are not allowed.\",\n    \"msgPrefixNotAllowed\": \"Branch prefix \\\"%s\\\" is not allowed.\",\n    \"msgPrefixSuggestion\": \"Instead of \\\"%s\\\" try \\\"%s\\\".\",\n    \"msgSeparatorRequired\": \"Branch \\\"%s\\\" must contain a separator \\\"%s\\\".\"\n  }\n}\n```\n\n2. Then reference this configuration in your workflow:\n\n```yaml\nname: Branch Name Lint\n\non:\n  push:\n    branches-ignore:\n      - main\n      - master\n  pull_request:\n    branches:\n      - main\n      - master\n\njobs:\n  lint-branch-name:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: actions/setup-node@v3\n        with:\n          node-version: '18'\n      - run: npm install branch-name-lint --no-save\n      - name: Extract branch name\n        shell: bash\n        run: |\n          if [ \"${{ github.event_name }}\" == \"pull_request\" ]; then\n            echo \"BRANCH_NAME=${{ github.head_ref }}\" \u003e\u003e $GITHUB_ENV\n          else\n            echo \"BRANCH_NAME=${GITHUB_REF#refs/heads/}\" \u003e\u003e $GITHUB_ENV\n          fi\n      - name: Check branch name\n        run: npx branch-name-lint .github/branch-name-lint.json\n        env:\n          BRANCH_NAME: ${{ env.BRANCH_NAME }}\n```\n\n### Handling Different Operating Systems\n\nWhen using branch-name-lint in a matrix strategy with multiple operating systems, ensure you use environment variables in a cross-platform way:\n\n```yaml\njobs:\n  lint-branch-name:\n    runs-on: ${{ matrix.os }}\n    strategy:\n      matrix:\n        os: [ubuntu-latest, windows-latest, macos-latest]\n    steps:\n      - uses: actions/checkout@v3\n      - uses: actions/setup-node@v3\n        with:\n          node-version: '18'\n      - run: npm install branch-name-lint --no-save\n      - name: Extract branch name\n        shell: bash\n        run: |\n          if [ \"${{ github.event_name }}\" == \"pull_request\" ]; then\n            echo \"BRANCH_NAME=${{ github.head_ref }}\" \u003e\u003e $GITHUB_ENV\n          else\n            echo \"BRANCH_NAME=${GITHUB_REF#refs/heads/}\" \u003e\u003e $GITHUB_ENV\n          fi\n      - name: Check branch name\n        run: npx branch-name-lint .github/branch-name-lint.json\n        env:\n          BRANCH_NAME: ${{ env.BRANCH_NAME }}\n```\n\nThis setup ensures that your branch naming conventions are enforced consistently across all contributions to your repository.\n\n## Usage in Node.js\n\n```js\nconst branchNameLint = require('branch-name-lint');\n\nbranchNameLint();\n//=\u003e 1 OR 0.\n```\n\n## API\n\n### branchNameLint([options])\n\n#### options\n\nType: `object`\nDefault:\n\n```\n{\n  prefixes: ['feature', 'hotfix', 'release'],\n  suggestions: {features: 'feature', feat: 'feature', fix: 'hotfix', releases: 'release'},\n  banned: ['wip'],\n  skip: [],\n  disallowed: ['master', 'develop', 'staging'],\n  separator: '/',\n  msgBranchBanned: 'Branches with the name \"%s\" are not allowed.',\n  msgBranchDisallowed: 'Pushing to \"%s\" is not allowed, use git-flow.',\n  msgPrefixNotAllowed: 'Branch prefix \"%s\" is not allowed.',\n  msgPrefixSuggestion: 'Instead of \"%s\" try \"%s\".',\n  msgSeparatorRequired: 'Branch \"%s\" must contain a separator \"%s\".'\n}\n```\n\n## License\n\nMIT © [Ran Bar-Zik](https://internet-israel.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarzik%2Fbranch-name-lint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbarzik%2Fbranch-name-lint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarzik%2Fbranch-name-lint/lists"}