Forge beautiful changelogs automatically from 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:
logsmith
```text
Generate a changelog and save to CHANGELOG.md:
```bash
logsmith --output CHANGELOG.md
```text
Generate changelog from specific commit range:
```bash
logsmith --from v1.0.0 --to HEAD
```typescript
Generate changelog in different formats:
```bash
# JSON format
logsmith --format json --output changelog.json
# HTML format
logsmith --format html --output changelog.html
# Auto-detect format from file extension
logsmith --output changelog.json # Automatically uses JSON format
logsmith --output changelog.html # Automatically uses HTML format
```text
### Programmatic Usage
```typescript
import { 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 written
```text
## CLI Commands
### Main Command
```bash
logsmith [options]
```text
**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
### Repository Statistics
```bash
logsmith stats [options]
```text
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:**
```text
📊 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 <john@example.com>
- Jane Smith <jane@example.com>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 <john@example.com>",
"breaking": false,
"references": []
}
]
}
],
"contributors": ["John Doe <john@example.com>"],
"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 bumpx patch
# Then generate changelog
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 💙