![\"project-logo\"](\"https://6jft62zmy9nx2oea.public.blob.vercel-storage.com/git-branch-lint-myXi2xH8jqeEIqScu1S9NymOOJVD9I.png\")
\n\n \n
CLI tool for consistent, enforceable Git branch naming.
\n\n## Table Of Contents\n\n- [Description](#description)\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [Clean Architecture Rules](#clean-architecture-rules)\n- [Development](#development)\n- [License](#license)\n\n## Description\n\n`@elsikora/git-branch-lint` validates branch names against team rules and includes an interactive branch-creation flow.\n\nThe project follows layered clean architecture:\n\n- `domain` - business rules, entities, policies, contracts\n- `application` - use cases and orchestration logic\n- `infrastructure` - adapters (git, config loading)\n- `presentation` - CLI controllers, prompts, formatters\n\n## Features\n\n- Template-driven branch validation using placeholders (for example `:type/:name` or `:scope/:type/:description`).\n- Optional ticket-id support with pattern `:type/:ticket-:name` (ticket part can be omitted).\n- Interactive branch creation command (`-b` / `--branch`) built directly from configured placeholders.\n- Branch constraints: prohibited names, min/max length, subject regex.\n- Helpful CLI error/hint formatting.\n- Cosmiconfig-based configuration discovery.\n\n## Installation\n\nInstall as a dev dependency:\n\n```bash\nnpm install --save-dev @elsikora/git-branch-lint\n```\n\nOr with other package managers:\n\n```bash\nyarn add -D @elsikora/git-branch-lint\npnpm add -D @elsikora/git-branch-lint\nbun add -d @elsikora/git-branch-lint\n```\n\n## Usage\n\nValidate current branch:\n\n```bash\nnpx @elsikora/git-branch-lint\n```\n\nStart interactive branch creation:\n\n```bash\nnpx @elsikora/git-branch-lint -b\n# or\nnpx @elsikora/git-branch-lint --branch\n```\n\nBehavior notes:\n\n- When `:ticket` is present in `branch-pattern`, both forms are valid:\n - with ticket: `feature/proj-123-user-authentication`\n - without ticket: `feature/user-authentication`\n- Interactive prompt normalizes ticket-id to lowercase before branch creation.\n- Placeholder prompts are generated from `branch-pattern` in declared order.\n- Validation and branch creation use the same template/pattern rules.\n\n## Configuration\n\nConfiguration is loaded via `cosmiconfig` (for example `package.json`, `.elsikora/git-branch-lint.config.js`, `.elsikora/git-branch-lint.config.ts`).\n\nRule semantics:\n\n- `branch-pattern` defines placeholders with `:placeholder` tokens.\n- Placeholder naming supports lowercase letters, digits, and hyphens (for example `:jira-ticket`).\n- `:type` is validated against configured `branches`.\n- `branch-subject-pattern` supports:\n - `string` - shared regex for all non-`type` placeholders.\n - `object` - regex per placeholder key (for example `scope`, `description`, `ticket`).\n- Optional placeholders are supported when the token is followed by `-` in `branch-pattern` (for example `:ticket-`).\n- Before branch creation, the final assembled name is validated again with full lint rules.\n\n### JavaScript Example\n\n```javascript\nexport default {\n\tbranches: {\n\t\tfeature: { title: \"Feature\", description: \"New functionality\" },\n\t\tbugfix: { title: \"Bugfix\", description: \"Bug fixes\" },\n\t\thotfix: { title: \"Hotfix\", description: \"Urgent fixes\" },\n\t},\n\tignore: [\"dev\"],\n\trules: {\n\t\t\"branch-pattern\": \":type/:ticket-:name\",\n\t\t\"branch-subject-pattern\": \"[a-z0-9-]+\",\n\t\t\"branch-prohibited\": [\"main\", \"master\", \"release\"],\n\t\t\"branch-min-length\": 5,\n\t\t\"branch-max-length\": 50,\n\t},\n};\n```\n\n### Advanced Placeholder Example\n\n```javascript\nexport default {\n\tbranches: [\"feat\", \"fix\", \"chore\"],\n\trules: {\n\t\t\"branch-pattern\": \":scope/:type/:description\",\n\t\t\"branch-subject-pattern\": {\n\t\t\tscope: \"(web|api|shared)\",\n\t\t\tdescription: \"[a-z0-9-]+\",\n\t\t},\n\t},\n};\n```\n\nValid branch example: `web/feat/shopping-cart`.\n\n### TypeScript Example\n\n```typescript\nimport type { IBranchLintConfig } from \"@elsikora/git-branch-lint\";\n\nconst config: IBranchLintConfig = {\n\tbranches: {\n\t\tfeature: { title: \"Feature\", description: \"New functionality\" },\n\t\tbugfix: { title: \"Bugfix\", description: \"Bug fixes\" },\n\t\thotfix: { title: \"Hotfix\", description: \"Urgent fixes\" },\n\t},\n\tignore: [\"dev\"],\n\trules: {\n\t\t\"branch-pattern\": \":type/:ticket-:name\",\n\t\t\"branch-subject-pattern\": \"[a-z0-9-]+\",\n\t\t\"branch-prohibited\": [\"main\", \"master\", \"release\"],\n\t\t\"branch-min-length\": 5,\n\t\t\"branch-max-length\": 50,\n\t},\n};\n\nexport default config;\n```\n\n### `package.json` Example\n\n```json\n{\n\t\"elsikora\": {\n\t\t\"git-branch-lint\": {\n\t\t\t\"branches\": [\"feature\", \"bugfix\", \"hotfix\"],\n\t\t\t\"rules\": {\n\t\t\t\t\"branch-pattern\": \":type/:ticket-:name\",\n\t\t\t\t\"branch-subject-pattern\": \"[a-z0-9-]+\",\n\t\t\t\t\"branch-prohibited\": [\"main\", \"master\", \"release\"]\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n## Clean Architecture Rules\n\nRepository standards enforced in this codebase:\n\n- Business rules live in `domain` and are consumed via `application` use cases.\n- `presentation` does I/O only; it must not own business validation rules.\n- `infrastructure` contains adapters only; default domain rules are defined outside adapter implementation.\n- `application` depends on domain contracts, not concrete infrastructure classes.\n- Types/interfaces are extracted into dedicated type/interface files for reusable contracts.\n- Import order and class member ordering are lint-enforced and must remain consistent.\n\n## Development\n\nCommon scripts:\n\n```bash\nnpm run lint\nnpm run lint:types\nnpm run test:unit\nnpm run test:e2e\n```\n\n## License\n\nMIT. See [`LICENSE`](LICENSE).\n","readmeFilename":"README.md"}