@elsikora/git-branch-lint 1.1.1-dev.2 → 1.1.1-dev.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +219 -125
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,14 +1,14 @@
1
1
  <p align="center">
2
- <img src="https://6jft62zmy9nx2oea.public.blob.vercel-storage.com/git-branch-lint-0rauIZprtXnHOrt840ZtTzrUK32erg.png" width="500" alt="project-logo">
2
+ <img src="https://6jft62zmy9nx2oea.public.blob.vercel-storage.com/git-branch-lint-myXi2xH8jqeEIqScu1S9NymOOJVD9I.png" width="500" alt="project-logo">
3
3
  </p>
4
4
 
5
- <h1 align="center">Git Branch Lint 🌿</h1>
6
- <p align="center"><em>Enforce consistent git branch naming conventions across your projects</em></p>
5
+ <h1 align="center">🌿 Git-Branch-Lint</h1>
6
+ <p align="center"><em>Enforce consistent Git branch naming conventions with style and ease</em></p>
7
7
 
8
8
  <p align="center">
9
9
  <a aria-label="ElsiKora logo" href="https://elsikora.com">
10
10
  <img src="https://img.shields.io/badge/MADE%20BY%20ElsiKora-333333.svg?style=for-the-badge" alt="ElsiKora">
11
- </a> <img src="https://img.shields.io/badge/version-blue.svg?style=for-the-badge&logo=npm&logoColor=white" alt="version"> <img src="https://img.shields.io/badge/typescript-blue.svg?style=for-the-badge&logo=typescript&logoColor=white" alt="typescript"> <img src="https://img.shields.io/badge/license-green.svg?style=for-the-badge&logo=license&logoColor=white" alt="license"> <img src="https://img.shields.io/badge/node-green.svg?style=for-the-badge&logo=node.js&logoColor=white" alt="node">
11
+ </a> <img src="https://img.shields.io/badge/TypeScript-3178C6.svg?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript"> <img src="https://img.shields.io/badge/Node.js-339933.svg?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js"> <img src="https://img.shields.io/badge/npm-CB3837.svg?style=for-the-badge&logo=npm&logoColor=white" alt="npm"> <img src="https://img.shields.io/badge/ESLint-4B32C3.svg?style=for-the-badge&logo=eslint&logoColor=white" alt="ESLint"> <img src="https://img.shields.io/badge/Prettier-F7B93E.svg?style=for-the-badge&logo=prettier&logoColor=black" alt="Prettier"> <img src="https://img.shields.io/badge/Vitest-6E9F18.svg?style=for-the-badge&logo=vitest&logoColor=white" alt="Vitest"> <img src="https://img.shields.io/badge/Rollup-EC4A3F.svg?style=for-the-badge&logo=rollup&logoColor=white" alt="Rollup"> <img src="https://img.shields.io/badge/Git-F05032.svg?style=for-the-badge&logo=git&logoColor=white" alt="Git"> <img src="https://img.shields.io/badge/GitHub%20Actions-2088FF.svg?style=for-the-badge&logo=github-actions&logoColor=white" alt="GitHub Actions">
12
12
  </p>
13
13
 
14
14
 
@@ -23,20 +23,26 @@
23
23
 
24
24
 
25
25
  ## 📖 Description
26
- Git Branch Lint is a powerful tool designed to maintain consistent git branch naming conventions in your development workflow. It helps teams enforce standardized branch naming patterns, prevent common naming mistakes, and maintain a clean git history. Built with TypeScript and following clean architecture principles, it provides flexible configuration options and helpful error messages to guide developers in following your team's branch naming conventions.
26
+ Git-Branch-Lint is a powerful, TypeScript-based CLI tool that brings order to your Git workflow by enforcing consistent branch naming conventions across your entire development team. Built with clean architecture principles, it not only validates branch names but also provides an interactive branch creation wizard that guides developers through creating properly formatted branches. Whether you're managing a small project or a large enterprise codebase, Git-Branch-Lint helps maintain a clean, organized repository structure that makes tracking features, fixes, and releases effortless. It seamlessly integrates with Git hooks, CI/CD pipelines, and supports multiple configuration formats, making it the perfect addition to any modern development workflow.
27
27
 
28
28
  ## 🚀 Features
29
- - ✨ **🔍 Validates branch names against customizable patterns**
30
- - ✨ **⚡ Fast and lightweight with minimal dependencies**
31
- - ✨ **🛠 Flexible configuration through multiple formats (JS, JSON, YAML)**
32
- - ✨ **💡 Helpful error messages with suggestions for fixing invalid names**
33
- - ✨ **🔒 Prevents usage of prohibited branch names**
34
- - ✨ **📏 Configurable length restrictions for branch names**
35
- - ✨ **🎨 Colored CLI output for better readability**
36
- - ✨ **🔧 Easy integration with git hooks and CI/CD pipelines**
29
+ - ✨ **🎯 **Smart Pattern Matching** - Define flexible branch naming patterns using simple placeholders like `:type/:name` that automatically validate against your configured branch types**
30
+ - ✨ **🚀 **Interactive Branch Creation** - Built-in wizard guides you through creating branches with beautiful prompts, ensuring compliance before the branch is even created**
31
+ - ✨ **🛡️ **Prohibited Branch Protection** - Prevent accidental use of protected branch names like 'main', 'master', or any custom prohibited names you define**
32
+ - ✨ **📏 **Length Validation** - Set minimum and maximum length constraints to keep branch names concise and meaningful**
33
+ - ✨ **🎨 **Beautiful CLI Output** - Colored terminal output with helpful error messages and hints that guide developers to fix issues quickly**
34
+ - ✨ **⚙️ **Flexible Configuration** - Support for multiple config formats (JS, TS, JSON, YAML) with intelligent config discovery via cosmiconfig**
35
+ - ✨ **🔄 **Git Hooks Ready** - Seamlessly integrate with Husky, lint-staged, or any Git hook manager for automatic validation**
36
+ - ✨ **📦 **Zero Config Option** - Works out of the box with sensible defaults while allowing complete customization when needed**
37
+ - ✨ **🏗️ **Clean Architecture** - Built with Domain-Driven Design principles, making the codebase maintainable and extensible**
37
38
 
38
39
  ## 🛠 Installation
39
40
  ```bash
41
+ ## 📦 Installation
42
+
43
+ Install Git-Branch-Lint as a development dependency in your project:
44
+
45
+
40
46
  # Using npm
41
47
  npm install --save-dev @elsikora/git-branch-lint
42
48
 
@@ -45,169 +51,257 @@ yarn add -D @elsikora/git-branch-lint
45
51
 
46
52
  # Using pnpm
47
53
  pnpm add -D @elsikora/git-branch-lint
54
+
55
+ # Using bun
56
+ bun add -d @elsikora/git-branch-lint
57
+
58
+
59
+ ### Global Installation
60
+
61
+ For system-wide usage across multiple projects:
62
+
63
+
64
+ npm install -g @elsikora/git-branch-lint
48
65
  ```
49
66
 
50
67
  ## 💡 Usage
51
- ## Basic Usage
68
+ ## 🚀 Usage
69
+
70
+ ### Basic Branch Validation
71
+
72
+ Validate your current Git branch name:
52
73
 
53
- Run the linter directly:
54
74
  ```bash
55
75
  npx @elsikora/git-branch-lint
56
76
  ```
57
77
 
58
- ## Configuration
78
+ ### Interactive Branch Creation
59
79
 
60
- Create a configuration file `.elsikora/.git-branch-lintrc.json`:
61
- ```json
62
- {
63
- "pattern": ":type/:name",
64
- "params": {
65
- "type": ["feature", "bugfix", "hotfix", "release"],
66
- "name": ["[a-z0-9-]+"]
67
- },
68
- "prohibited": ["master", "main", "develop"],
69
- "minLength": 5,
70
- "maxLength": 50
71
- }
80
+ Create a new branch with the interactive wizard:
81
+
82
+ ```bash
83
+ npx @elsikora/git-branch-lint -b
84
+ # or
85
+ npx @elsikora/git-branch-lint --branch
72
86
  ```
73
87
 
74
- ## Git Hooks Integration
88
+ ### Configuration
75
89
 
76
- Add to your `package.json`:
77
- ```json
78
- {
79
- "husky": {
80
- "hooks": {
81
- "pre-commit": "npx @elsikora/git-branch-lint"
82
- }
83
- }
84
- }
85
- ```
90
+ Git-Branch-Lint uses [cosmiconfig](https://github.com/davidtheclark/cosmiconfig) for configuration file discovery. Create any of these files:
86
91
 
87
- ## Advanced Usage
92
+ #### JavaScript Configuration (`.elsikora/git-branch-lint.config.js`)
88
93
 
89
- Custom configuration in JavaScript (`.elsikora/git-branch-lint.config.js`):
90
94
  ```javascript
91
- module.exports = {
95
+ export default {
92
96
  branches: {
93
- bugfix: { description: "🐞 Fixing issues in existing functionality", title: "Bugfix" },
94
- feature: { description: "🆕 Integration of new functionality", title: "Feature" },
95
- hotfix: { description: "🚑 Critical fixes for urgent issues", title: "Hotfix" },
96
- release: { description: "📦 Preparing a new release version", title: "Release" },
97
- support: { description: "🛠️ Support and maintenance tasks", title: "Support" },
98
- },
99
- ignore: ["dev"],
100
- rules: {
101
- "branch-max-length": 50,
102
- "branch-min-length": 5,
103
- "branch-pattern": ":type/:name",
104
- "branch-prohibited": ["main", "master", "release"],
105
- "branch-subject-pattern": "[a-z0-9-]+",
106
- },
107
- }
97
+ feature: {
98
+ title: "Feature",
99
+ description: "🆕 New functionality"
100
+ },
101
+ bugfix: {
102
+ title: "Bugfix",
103
+ description: "🐛 Bug fixes"
104
+ },
105
+ hotfix: {
106
+ title: "Hotfix",
107
+ description: "🚑 Urgent production fixes"
108
+ },
109
+ release: {
110
+ title: "Release",
111
+ description: "📦 Release preparation"
112
+ },
113
+ chore: {
114
+ title: "Chore",
115
+ description: "🔧 Maintenance tasks"
116
+ }
117
+ },
118
+ ignore: ["dev", "develop", "staging"],
119
+ rules: {
120
+ "branch-pattern": ":type/:name",
121
+ "branch-subject-pattern": "[a-z0-9-]+",
122
+ "branch-prohibited": ["main", "master", "prod"],
123
+ "branch-min-length": 5,
124
+ "branch-max-length": 60
125
+ }
126
+ };
108
127
  ```
109
128
 
110
- Typescript support (`.elsikora/git-branch-lint.config.ts`):
129
+ #### TypeScript Configuration (`.elsikora/git-branch-lint.config.ts`)
130
+
111
131
  ```typescript
112
- import type { BranchLintConfig } from "@elsikora/git-branch-lint";
113
-
114
- const config: BranchLintConfig = {
115
- branches: {
116
- bugfix: { description: "🆕 Integration of new functionality", title: "Feature" },
117
- feature: { description: "🐞 Fixing issues in existing functionality", title: "Bugfix" },
118
- hotfix: { description: "🚑 Critical fixes for urgent issues", title: "Hotfix" },
119
- release: { description: "📦 Preparing a new release version", title: "Release" },
120
- support: { description: "🛠️ Support and maintenance tasks", title: "Support" },
121
- },
122
- ignore: [dev],
123
- rules: {
124
- "branch-max-length": 50,
125
- "branch-min-length": 5,
126
- "branch-pattern": ":type/:name",
127
- "branch-prohibited": ["main", "master", "release"],
128
- "branch-subject-pattern": "[a-z0-9-]+",
129
- },
132
+ import type { IBranchLintConfig } from '@elsikora/git-branch-lint';
133
+
134
+ const config: IBranchLintConfig = {
135
+ branches: {
136
+ feat: { title: "Feature", description: "✨ New features" },
137
+ fix: { title: "Fix", description: "🐛 Bug fixes" },
138
+ docs: { title: "Docs", description: "📚 Documentation" },
139
+ style: { title: "Style", description: "💄 Styling" },
140
+ refactor: { title: "Refactor", description: "♻️ Code refactoring" },
141
+ perf: { title: "Performance", description: "⚡ Performance improvements" },
142
+ test: { title: "Test", description: "✅ Testing" },
143
+ build: { title: "Build", description: "📦 Build system" },
144
+ ci: { title: "CI", description: "👷 CI/CD" }
145
+ },
146
+ rules: {
147
+ "branch-pattern": ":type/:name",
148
+ "branch-subject-pattern": "[a-z0-9-]+",
149
+ "branch-min-length": 8,
150
+ "branch-max-length": 72
151
+ }
130
152
  };
131
153
 
132
154
  export default config;
133
155
  ```
134
156
 
135
- ## Create branch tool
157
+ #### Package.json Configuration
136
158
 
137
- Create branch tool is a command-line utility included in the @elsikora/branch-lint package. It facilitates the creation of Git branches by guiding users through an interactive prompt to select a branch type and name, ensuring compliance with the project's branch naming conventions as defined in the configuration.
138
-
139
- Example:
140
- ```bash
141
- npx @elsikora/branch-lint -b
159
+ ```json
160
+ {
161
+ "elsikora": {
162
+ "git-branch-lint": {
163
+ "branches": ["feature", "bugfix", "hotfix"],
164
+ "rules": {
165
+ "branch-pattern": ":type/:name",
166
+ "branch-prohibited": ["main", "master"]
167
+ }
168
+ }
169
+ }
170
+ }
142
171
  ```
143
172
 
144
- Prompts:
173
+ ### Git Hooks Integration
174
+
175
+ #### With Husky
176
+
145
177
  ```bash
146
- 🌿 Creating a new branch...
178
+ # Install Husky
179
+ npm install --save-dev husky
147
180
 
148
- ❔ Select the type of branch you're creating:
149
- Feature: 🆕 Integration of new functionality
150
- Bugfix: 🐞 Fixing issues in existing functionality
151
- ❯ Hotfix: 🚑 Critical fixes for urgent issues
152
- Release: 📦 Preparing a new release version
153
- Support: 🛠️ Support and maintenance tasks
181
+ # Initialize Husky
182
+ npx husky init
154
183
 
155
- Enter the branch name (e.g., authorization): new-ui
184
+ # Add pre-push hook
185
+ echo "npx @elsikora/git-branch-lint" > .husky/pre-push
186
+ ```
156
187
 
157
- ⌛️ Creating branch: feature/new-ui
158
- Do you want to push the branch to the remote repository? (y/N) y
188
+ #### With lint-staged
159
189
 
160
- ✅ Branch feature/new-ui pushed to remote repository!
190
+ ```javascript
191
+ // lint-staged.config.js
192
+ export default {
193
+ '*': () => 'npx @elsikora/git-branch-lint'
194
+ };
161
195
  ```
162
196
 
163
- ## CI/CD Integration
197
+ ### CI/CD Integration
198
+
199
+ #### GitHub Actions
164
200
 
165
- GitHub Actions example:
166
201
  ```yaml
167
- name: Lint Branch Names
168
- on: [push]
202
+ name: Branch Lint
203
+ on: [push, pull_request]
169
204
 
170
205
  jobs:
171
- lint:
206
+ lint-branch:
172
207
  runs-on: ubuntu-latest
173
208
  steps:
174
- - uses: actions/checkout@v2
175
- - uses: actions/setup-node@v2
176
- - run: npm install
209
+ - uses: actions/checkout@v4
210
+ - uses: actions/setup-node@v4
211
+ with:
212
+ node-version: '20'
213
+ - run: npm ci
177
214
  - run: npx @elsikora/git-branch-lint
178
215
  ```
179
216
 
217
+ #### GitLab CI
218
+
219
+ ```yaml
220
+ branch-lint:
221
+ stage: test
222
+ script:
223
+ - npm ci
224
+ - npx @elsikora/git-branch-lint
225
+ only:
226
+ - branches
227
+ ```
228
+
229
+ ### Advanced Patterns
230
+
231
+ #### Jira Integration Pattern
232
+
233
+ ```javascript
234
+ {
235
+ rules: {
236
+ "branch-pattern": ":type/:ticket-:description",
237
+ "branch-subject-pattern": {
238
+ "ticket": "[A-Z]{2,}-[0-9]+",
239
+ "description": "[a-z0-9-]+"
240
+ }
241
+ }
242
+ }
243
+ // Valid: feature/PROJ-123-user-authentication
244
+ ```
245
+
246
+ #### Monorepo Pattern
247
+
248
+ ```javascript
249
+ {
250
+ rules: {
251
+ "branch-pattern": ":scope/:type/:name",
252
+ "branch-subject-pattern": {
253
+ "scope": "(web|api|shared|docs)",
254
+ "type": "(feat|fix|chore)",
255
+ "name": "[a-z0-9-]+"
256
+ }
257
+ }
258
+ }
259
+ // Valid: web/feat/shopping-cart
260
+ ```
261
+
180
262
  ## 🛣 Roadmap
181
263
  | Task / Feature | Status |
182
- |---------------|--------|
183
- | - Add support for custom error messages | 🚧 In Progress |
184
- | - Implement branch name suggestions when validation fails | 🚧 In Progress |
185
- | - Add support for regex-based branch name validation | 🚧 In Progress |
186
- | - Create GitHub Action for easier CI integration | 🚧 In Progress |
187
- | - Add support for branch name templates | 🚧 In Progress |
188
- | - Implement branch name statistics and reporting | 🚧 In Progress |
189
- | (done) 🔍 Validates branch names against customizable patterns | 🚧 In Progress |
190
- | (done) ⚡ Fast and lightweight with minimal dependencies | 🚧 In Progress |
191
- | (done) 🛠 Flexible configuration through multiple formats (JS, JSON, YAML) | 🚧 In Progress |
264
+ |----------------|--------|
265
+ | Core branch validation engine | ✅ Done |
266
+ | Interactive branch creation wizard | ✅ Done |
267
+ | Multiple configuration format support | ✅ Done |
268
+ | TypeScript support | ✅ Done |
269
+ | Comprehensive test coverage | ✅ Done |
270
+ | VS Code extension | 🚧 In Progress |
271
+ | Branch name auto-suggestions | 🚧 In Progress |
272
+ | Custom validation rules plugin system | 🚧 In Progress |
273
+ | Branch naming statistics dashboard | 🚧 In Progress |
274
+ | Integration with popular Git GUIs | 🚧 In Progress |
275
+ | AI-powered branch name generator | 🚧 In Progress |
192
276
 
193
277
  ## ❓ FAQ
194
- ### Why should I use Git Branch Lint?
195
- Maintaining consistent branch naming conventions helps teams track work effectively and automate processes like deployment and versioning.
278
+ ## ❓ Frequently Asked Questions
196
279
 
197
- ### Can I use custom regular expressions?
198
- Yes, you can define custom regex patterns in the configuration file's `params` section.
280
+ ### **Q: Can I use this with existing branches?**
281
+ A: Yes! The `ignore` configuration option allows you to exclude existing branches from validation. This is perfect for grandfathering in old branches while enforcing rules on new ones.
199
282
 
200
- ### How do I skip validation for certain branches?
201
- You can exclude branches by adding them to the `prohibited` list with a negative pattern.
283
+ ### **Q: How do I handle different patterns for different teams?**
284
+ A: You can create team-specific configuration files and use environment variables or Git config to load the appropriate one:
285
+ ```bash
286
+ GIT_BRANCH_LINT_CONFIG=.team-frontend.config.js npx @elsikora/git-branch-lint
287
+ ```
202
288
 
203
- ### Does it work with monorepos?
204
- Yes, you can configure different patterns for different parts of your monorepo using workspace-specific configuration files.
289
+ ### **Q: Can I validate branch names in my IDE?**
290
+ A: While we're working on official IDE extensions, you can configure your IDE to run the validation as an external tool or use it with pre-commit hooks.
205
291
 
206
- ## 🔒 License
207
- This project is licensed under **MIT License
292
+ ### **Q: What happens if I try to push an invalid branch?**
293
+ A: When integrated with Git hooks, the push will be prevented and you'll see a helpful error message explaining what's wrong and how to fix it.
294
+
295
+ ### **Q: Can I use custom regex patterns?**
296
+ A: Absolutely! The `branch-subject-pattern` rule accepts any valid JavaScript regex pattern, giving you complete control over validation.
208
297
 
209
- Copyright (c) 2025 ElsiKora
298
+ ### **Q: Is this compatible with Git Flow or GitHub Flow?**
299
+ A: Yes! The default configuration works well with both workflows, and you can easily customize it to match your specific flow requirements.
210
300
 
211
- Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
301
+ ### **Q: How do I migrate from other branch linting tools?**
302
+ A: Git-Branch-Lint's configuration is designed to be intuitive. Most configurations from other tools can be adapted by mapping their patterns to our rule system.
303
+
304
+ ## 🔒 License
305
+ This project is licensed under **MIT License - see the [LICENSE](LICENSE) file for details.
212
306
 
213
- The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.**.
307
+ Maintained with ❤️ by [ElsiKora](https://github.com/ElsiKora)**.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@elsikora/git-branch-lint",
3
- "version": "1.1.1-dev.2",
3
+ "version": "1.1.1-dev.3",
4
4
  "description": "Lint your git branch names",
5
5
  "keywords": [
6
6
  "lint",