🌿 Git-Branch-Lint

Enforce consistent Git branch naming conventions with style and ease

📚 Table of Contents

• Description
• Features
• Installation
• Usage
• Roadmap
• FAQ
• License

📖 Description

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.

🚀 Features

• ✨ 🎯 Smart Pattern Matching - Define flexible branch naming patterns using simple placeholders like :type/:name that automatically validate against your configured branch types
• ✨ 🚀 Interactive Branch Creation - Built-in wizard guides you through creating branches with beautiful prompts, ensuring compliance before the branch is even created
• ✨ 🛡️ Prohibited Branch Protection - Prevent accidental use of protected branch names like 'main', 'master', or any custom prohibited names you define
• ✨ 📏 Length Validation - Set minimum and maximum length constraints to keep branch names concise and meaningful
• ✨ 🎨 Beautiful CLI Output - Colored terminal output with helpful error messages and hints that guide developers to fix issues quickly
• ✨ ⚙️ Flexible Configuration - Support for multiple config formats (JS, TS, JSON, YAML) with intelligent config discovery via cosmiconfig
• ✨ 🔄 Git Hooks Ready - Seamlessly integrate with Husky, lint-staged, or any Git hook manager for automatic validation
• ✨ 📦 Zero Config Option - Works out of the box with sensible defaults while allowing complete customization when needed
• ✨ 🏗️ Clean Architecture - Built with Domain-Driven Design principles, making the codebase maintainable and extensible

🛠 Installation

1## 📦 Installation
2
3Install Git-Branch-Lint as a development dependency in your project:
4
5
6# Using npm
7npm install --save-dev @elsikora/git-branch-lint
8
9# Using yarn
10yarn add -D @elsikora/git-branch-lint
11
12# Using pnpm
13pnpm add -D @elsikora/git-branch-lint
14
15# Using bun
16bun add -d @elsikora/git-branch-lint
17
18
19### Global Installation
20
21For system-wide usage across multiple projects:
22
23
24npm install -g @elsikora/git-branch-lint

💡 Usage

🚀 Usage

Basic Branch Validation

Validate your current Git branch name:

1npx @elsikora/git-branch-lint

Interactive Branch Creation

Create a new branch with the interactive wizard:

1npx @elsikora/git-branch-lint -b
2# or
3npx @elsikora/git-branch-lint --branch

Configuration

Git-Branch-Lint uses cosmiconfig for configuration file discovery. Create any of these files:

JavaScript Configuration (.elsikora/git-branch-lint.config.js)

1export default {
2  branches: {
3    feature: { 
4      title: "Feature", 
5      description: "🆕 New functionality" 
6    },
7    bugfix: { 
8      title: "Bugfix", 
9      description: "🐛 Bug fixes" 
10    },
11    hotfix: { 
12      title: "Hotfix", 
13      description: "🚑 Urgent production fixes" 
14    },
15    release: { 
16      title: "Release", 
17      description: "📦 Release preparation" 
18    },
19    chore: { 
20      title: "Chore", 
21      description: "🔧 Maintenance tasks" 
22    }
23  },
24  ignore: ["dev", "develop", "staging"],
25  rules: {
26    "branch-pattern": ":type/:name",
27    "branch-subject-pattern": "[a-z0-9-]+",
28    "branch-prohibited": ["main", "master", "prod"],
29    "branch-min-length": 5,
30    "branch-max-length": 60
31  }
32};

TypeScript Configuration (.elsikora/git-branch-lint.config.ts)

1import type { IBranchLintConfig } from '@elsikora/git-branch-lint';
2
3const config: IBranchLintConfig = {
4  branches: {
5    feat: { title: "Feature", description: "✨ New features" },
6    fix: { title: "Fix", description: "🐛 Bug fixes" },
7    docs: { title: "Docs", description: "📚 Documentation" },
8    style: { title: "Style", description: "💄 Styling" },
9    refactor: { title: "Refactor", description: "♻️ Code refactoring" },
10    perf: { title: "Performance", description: "⚡ Performance improvements" },
11    test: { title: "Test", description: "✅ Testing" },
12    build: { title: "Build", description: "📦 Build system" },
13    ci: { title: "CI", description: "👷 CI/CD" }
14  },
15  rules: {
16    "branch-pattern": ":type/:name",
17    "branch-subject-pattern": "[a-z0-9-]+",
18    "branch-min-length": 8,
19    "branch-max-length": 72
20  }
21};
22
23export default config;

Package.json Configuration

1{
2  "elsikora": {
3    "git-branch-lint": {
4      "branches": ["feature", "bugfix", "hotfix"],
5      "rules": {
6        "branch-pattern": ":type/:name",
7        "branch-prohibited": ["main", "master"]
8      }
9    }
10  }
11}

Git Hooks Integration

With Husky

1# Install Husky
2npm install --save-dev husky
3
4# Initialize Husky
5npx husky init
6
7# Add pre-push hook
8echo "npx @elsikora/git-branch-lint" > .husky/pre-push

With lint-staged

1// lint-staged.config.js
2export default {
3  '*': () => 'npx @elsikora/git-branch-lint'
4};

CI/CD Integration

GitHub Actions

1name: Branch Lint
2on: [push, pull_request]
3
4jobs:
5  lint-branch:
6    runs-on: ubuntu-latest
7    steps:
8      - uses: actions/checkout@v4
9      - uses: actions/setup-node@v4
10        with:
11          node-version: '20'
12      - run: npm ci
13      - run: npx @elsikora/git-branch-lint

GitLab CI

1branch-lint:
2  stage: test
3  script:
4    - npm ci
5    - npx @elsikora/git-branch-lint
6  only:
7    - branches

Advanced Patterns

Jira Integration Pattern

1{
2  rules: {
3    "branch-pattern": ":type/:ticket-:description",
4    "branch-subject-pattern": {
5      "ticket": "[A-Z]{2,}-[0-9]+",
6      "description": "[a-z0-9-]+"
7    }
8  }
9}
10// Valid: feature/PROJ-123-user-authentication

Monorepo Pattern

1{
2  rules: {
3    "branch-pattern": ":scope/:type/:name",
4    "branch-subject-pattern": {
5      "scope": "(web|api|shared|docs)",
6      "type": "(feat|fix|chore)",
7      "name": "[a-z0-9-]+"
8    }
9  }
10}
11// Valid: web/feat/shopping-cart

🛣 Roadmap

Task / Feature	Status
Core branch validation engine	✅ Done
Interactive branch creation wizard	✅ Done
Multiple configuration format support	✅ Done
TypeScript support	✅ Done
Comprehensive test coverage	✅ Done
VS Code extension	🚧 In Progress
Branch name auto-suggestions	🚧 In Progress
Custom validation rules plugin system	🚧 In Progress
Branch naming statistics dashboard	🚧 In Progress
Integration with popular Git GUIs	🚧 In Progress
AI-powered branch name generator	🚧 In Progress

❓ FAQ

❓ Frequently Asked Questions

Q: Can I use this with existing branches?

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.

Q: How do I handle different patterns for different teams?

A: You can create team-specific configuration files and use environment variables or Git config to load the appropriate one:

1GIT_BRANCH_LINT_CONFIG=.team-frontend.config.js npx @elsikora/git-branch-lint

Q: Can I validate branch names in my IDE?

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.

Q: What happens if I try to push an invalid branch?

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.

Q: Can I use custom regex patterns?

A: Absolutely! The branch-subject-pattern rule accepts any valid JavaScript regex pattern, giving you complete control over validation.

Q: Is this compatible with Git Flow or GitHub Flow?

A: Yes! The default configuration works well with both workflows, and you can easily customize it to match your specific flow requirements.

Q: How do I migrate from other branch linting tools?

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.

🔒 License

This project is licensed under **MIT License - see the LICENSE file for details.

Maintained with ❤️ by ElsiKora**.