commit-from-branch

⚠️ Package Migration Notice This package was previously published as @253eosam/commit-from-branch. Please use commit-from-branch instead. The scoped package is deprecated.

Flexible commit message templating from branch name (ticket/segments) for Husky's prepare-commit-msg hook.

Automatically formats your commit messages based on your branch name, extracting Jira-style tickets (e.g., ABC-123) and supporting flexible templating with branch segments.

Features

• 🎯 Automatic ticket extraction - Finds Jira-style tickets (ABC-123) in branch names
• 🔧 Flexible templating - Customizable commit message formats with placeholders
• 🌿 Branch segment support - Access individual parts of your branch path
• ⚡ Zero configuration - Works out of the box with sensible defaults
• 🪝 Husky integration - Easy setup with Husky's prepare-commit-msg hook
• 🎨 Pattern matching - Include/exclude branches with glob patterns
• 🏃 Fast & lightweight - Minimal dependencies, TypeScript-based

📖 Table of Contents

• Demo
• Installation
• Quick Start
• Configuration
• Template Variables
• Examples
• Debug Mode
• Programmatic Usage
• How It Works
• Requirements
• Contributing
• Links

🌐 Demo

🚀 Live Demo - Try the interactive demo to see how commit message templating works!

📦 Installation

npm install commit-from-branch --save-dev

Note: This package requires Husky v9 as a peer dependency. npm will automatically warn you if it's not installed.

🚀 Quick Start

1. Install Husky v9 (if not already installed):

npm install --save-dev husky@^9.0.0
npx husky init

2. Setup the hook:

npx cfb init

3. Configure in package.json (optional):

{
  "commitFromBranch": {
    "format": "[${ticket}] ${msg}",
    "fallbackFormat": "[${seg0}] ${msg}",
    "includePattern": ["feature/*", "bugfix/*"]
  }
}

4. Create a branch and commit:

git checkout -b feature/ABC-123-add-login
git add .
git commit -m "implement user authentication"
# Result: "[ABC-123] implement user authentication"

⚙️ Configuration

Add configuration to your package.json:

{
  "commitFromBranch": {
    "format": "[${ticket}] ${msg}",
    "fallbackFormat": "[${seg0}] ${msg}",
    "includePattern": ["*"],
    "exclude": ["merge", "squash", "revert"]
  }
}

Configuration Options

Option	Type	Default	Description
format	string	"[${ticket}] ${msg}"	Template when ticket is found
fallbackFormat	string	"[${seg0}] ${msg}"	Template when no ticket found
includePattern	string | string[]	["*"]	Glob patterns for branches to include
exclude	string[]	["merge", "squash", "revert"]	Commit sources to exclude

🔧 Template Variables

Use these placeholders in your format templates:

Variable	Description	Example
${ticket}	Extracted ticket (ABC-123 format)	ABC-123
${branch}	Full branch name	feature/ABC-123-add-login
${seg0}, ${seg1}, etc.	Branch segments split by /	feature, ABC-123-add-login
${segments}	All segments joined with /	feature/ABC-123-add-login
${prefix:n}	First n segments joined with /	${prefix:2} → feature/ABC-123-add-login
${msg}	Original commit message	implement user authentication
${body}	Full original commit body	Multi-line commit content

💡 Examples

Basic Ticket Extraction

# Branch: feature/ABC-123-user-login
# Commit: git commit -m "add login form"
# Result: "[ABC-123] add login form"

Fallback Format (No Ticket)

# Branch: feature/user-dashboard
# Commit: git commit -m "create dashboard"
# Result: "[feature] create dashboard"

Custom Formatting

{
  "commitFromBranch": {
    "format": "${ticket}: ${msg}",
    "fallbackFormat": "${seg0}/${seg1}: ${msg}"
  }
}

# Branch: bugfix/payment/ABC-456-fix-checkout
# Result: "ABC-456: fix payment processing"

Pattern Matching

{
  "commitFromBranch": {
    "includePattern": ["feature/*", "bugfix/*", "hotfix/*"],
    "exclude": ["merge", "squash"]
  }
}

Advanced Templates

{
  "commitFromBranch": {
    "format": "[${ticket}] ${seg0}: ${msg}",
    "fallbackFormat": "[${prefix:2}] ${msg}"
  }
}

🐛 Debug Mode

Enable debug logging:

BRANCH_PREFIX_DEBUG=1 git commit -m "test message"

🧪 Dry Run Mode

Test without modifying commit messages:

BRANCH_PREFIX_DRYRUN=1 git commit -m "test message"

🔌 Programmatic Usage

import { run } from "commit-from-branch";

// Use with custom options
const exitCode = run({
  argv: ["node", "script.js", "/path/to/COMMIT_EDITMSG"],
  env: process.env,
  cwd: "/path/to/repo",
});

import { initHusky } from "commit-from-branch/init";

// Setup Husky hook programmatically
initHusky("/path/to/repo");

⚡ How It Works

1. Hook Integration: Integrates with Husky's prepare-commit-msg hook
2. Branch Detection: Gets current branch name using git rev-parse --abbrev-ref HEAD
3. Pattern Matching: Checks if branch matches include patterns and isn't excluded
4. Ticket Extraction: Uses regex /([A-Z]+-\d+)/i to find Jira-style tickets
5. Template Rendering: Replaces placeholders with actual values
6. Message Formatting: Updates commit message file with formatted result

📋 Requirements

• Node.js >= 16
• Git repository
• Husky v9 (peer dependency)

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes and add tests
4. Run the build: npm run build
5. Commit your changes: git commit -m "add my feature"
6. Push to the branch: git push origin feature/my-feature
7. Submit a pull request

🔗 Links

Package & Releases

• 📦 NPM Package - Official NPM package
• 🚀 GitHub Releases - Release notes and downloads
• 🌐 Live Demo - Interactive demo

Development & Community

• 💻 Source Code - GitHub repository
• 🐛 Report Issues - Bug reports and feature requests
• 📊 CI/CD Pipeline - Build status and automation
• 📈 NPM Stats - Download statistics

Documentation

• 📚 API Documentation - Programmatic usage guide
• ⚙️ Configuration Guide - Setup and customization
• 🔧 Template Variables - Available placeholders

📄 License

MIT © 253eosam

---

⬆ Back to Top

Made with ❤️ by 253eosam