Forge beautiful changelogs automatically using conventional commits.
- 🚀 Automatic changelog generation from conventional commits
- 🎨 Beautiful formatting with emojis and proper grouping
- 🔄 Multiple output formats - Markdown, JSON, and HTML
- 📊 Repository statistics with comprehensive trend analysis
- ⚙️ Highly configurable with TypeScript config files
- 🔧 CLI and programmatic API for all use cases
- 📝 Conventional commits parsing and analysis
- 👥 Author filtering and management
- 🔗 Git repository integration with compare URLs
- 🌍 Multi-repository support
Generate a changelog and display in console:
bunx logsmithGenerate a changelog and save to CHANGELOG.md:
bunx logsmith --output CHANGELOG.mdGenerate changelog from specific commit range:
bunx logsmith --from v1.0.0 --to HEADGenerate changelog in different formats:
# JSON format
bunx logsmith --format json --output changelog.json
# HTML format
bunx logsmith --format html --output changelog.html
# Auto-detect format from file extension
bunx logsmith --output changelog.json # Automatically uses JSON format
bunx logsmith --output changelog.html # Automatically uses HTML formatimport { generateChangelog } from 'logsmith'
// Generate changelog
const result = await generateChangelog({
dir: process.cwd(),
from: 'v1.0.0',
to: 'HEAD',
output: 'CHANGELOG.md',
verbose: true,
// ... other options
})
console.log(result.content) // Changelog content
console.log(result.outputPath) // Path where changelog was writtenlogsmith [options]Core Options:
--from <ref>- Start commit reference (default: latest git tag)--to <ref>- End commit reference (default: HEAD)--dir <dir>- Path to git repository (default: current directory)--output <file>- Changelog file name (default: CHANGELOG.md)--format <format>- Output format: markdown, json, html (default: markdown)--no-output- Write to console only--verbose- Enable verbose logging
Author Filtering:
--exclude-authors <authors>- Skip contributors (comma-separated)--include-authors <authors>- Include only specific contributors (comma-separated)--hide-author-email- Do not include author email in changelog
Advanced Filtering:
--exclude-types <types>- Exclude commit types (comma-separated)--include-types <types>- Include only specific commit types (comma-separated)--exclude-scopes <scopes>- Exclude commit scopes (comma-separated)--include-scopes <scopes>- Include only specific commit scopes (comma-separated)--min-commits <number>- Minimum commits required to include a section--max-commits <number>- Maximum commits per section (0 = unlimited)--max-length <number>- Maximum description length (0 = unlimited)
Formatting Options:
--no-dates- Hide dates from changelog--no-breaking-group- Don't group breaking changes separately--include-body- Include commit body in changelog entries--no-linkify- Don't linkify issues and PRs
logsmith stats [options]Analyze your repository and display comprehensive statistics with trend analysis.
Options:
--from <ref>- Start commit reference (default: latest git tag)--to <ref>- End commit reference (default: HEAD)--dir <dir>- Path to git repository (default: current directory)--json- Output in JSON format--verbose- Enable verbose logging
Example Output:
📊 Repository Statistics
─────────────────────────
Range: v1.0.0 → HEAD
Total commits: 127
Contributors: 8
Breaking changes: 3
📈 Commit Frequency
───────────────────
Total days with commits: 45
Average commits per day: 2.82
Peak day: 2024-03-15 (12 commits)
Recent activity:
2024-03-20: ████ 4
2024-03-19: ██ 2
2024-03-18: ██████ 6
👥 Contributors
──────────────
Most active: John Doe (42 commits)
New contributors: 3
Top contributors:
John Doe: 42 commits (33.1%)
Jane Smith: 28 commits (22.0%)
Bob Johnson: 19 commits (15.0%)
📋 Commit Types
──────────────
Most common: feat (35.4%)
Least common: revert (0.8%)
Distribution:
feat : ███████ 35.4% (45)
fix : █████ 24.4% (31)
docs : ██ 11.8% (15)
refactor : ██ 9.4% (12)
Logsmith can be configured using a logsmith.config.ts file:
import { defineConfig } from 'logsmith'
export default defineConfig({
output: 'CHANGELOG.md',
// Changelog options
hideAuthorEmail: false,
excludeAuthors: ['dependabot[bot]', 'github-actions[bot]'],
// Templates and formatting
templates: {
commitFormat: '- {{scope}}{{description}} ([{{hash}}]({{repoUrl}}/commit/{{hash}}))',
typeFormat: {
feat: '🚀 Features',
fix: '🐛 Bug Fixes',
docs: '📚 Documentation',
// ... customize as needed
},
},
// Repository configuration
repo: 'https://github.com/your-org/your-repo',
verbose: true,
})interface LogsmithConfig {
// Core options
verbose: boolean
output: string | false
from?: string
to: string
dir: string
// Changelog options
clean: boolean
excludeAuthors: string[]
includeAuthors: string[]
excludeEmail: boolean
hideAuthorEmail: boolean
// Repository configuration
repo?: string
github: {
repo?: string
token?: string
}
// Templates and formatting
templates: {
commitFormat: string
groupFormat: string
typeFormat: Record<string, string>
}
}Logsmith parses conventional commits and groups them by type:
feat: add new authentication system
fix: resolve memory leak in parser
docs: update API documentation
style: fix code formatting
refactor: simplify user service
perf: optimize database queries
test: add integration tests
build: update dependencies
ci: improve GitHub Actions workflow
chore: update development tools
Breaking changes are detected and highlighted:
feat!: remove deprecated API endpoints
feat: add new feature
BREAKING CHANGE: The old API has been removed
Logsmith supports multiple output formats to meet different needs:
Standard markdown format perfect for GitHub repositories:
### 🚀 Features
- **auth**: add OAuth integration ([abc123d](https://github.com/your-org/your-repo/commit/abc123d))
- **api**: implement rate limiting ([def456a](https://github.com/your-org/your-repo/commit/def456a))
### 🐛 Bug Fixes
- **parser**: fix memory leak in token processing ([ghi789b](https://github.com/your-org/your-repo/commit/ghi789b))
### Contributors
- John Doe <[email protected]>
- Jane Smith <[email protected]>Structured data format for automation and tooling:
{
"date": "2024-03-20",
"sections": [
{
"title": "🚀 Features",
"commits": [
{
"type": "feat",
"scope": "auth",
"description": "add OAuth integration",
"hash": "abc123d",
"author": "John Doe <[email protected]>",
"breaking": false,
"references": []
}
]
}
],
"contributors": ["John Doe <[email protected]>"],
"stats": {
"totalCommits": 15,
"sectionsCount": 3,
"contributorsCount": 4,
"breakingChanges": 1
}
}Beautiful web-ready format with modern styling:
- Clean, responsive design
- Syntax highlighting for commit hashes
- Interactive links to commits and issues
- Mobile-friendly layout
- Professional typography
- Breaking change indicators
Generate changelog content with optional file output.
Returns:
interface ChangelogResult {
content: string // Generated changelog content
outputPath?: string // Path where changelog was written (if output option used)
}TypeScript helper for configuration files.
Logsmith focuses solely on changelog generation. For version bumping functionality, use it together with @stacksjs/bumpx:
# First bump the version
bunx logsmith patch
# Then generate changelog
bunx logsmith --output CHANGELOG.mdOr use them together in your build scripts:
{
"scripts": {
"release": "logsmith patch && logsmith --output CHANGELOG.md"
}
}- changelogen - Thanks for the initial inspiration!
- Chris Breuer
- All Contributors
We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.
The MIT License (MIT). Please see LICENSE for more information.
Made with 💙