@stacksjs/logsmith
Advanced tools
Forge beautiful changelogs automatically using conventional commits.
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
```text
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]
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 loggingAuthor 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 changelogAdvanced 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 PRslogsmith 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 loggingExample 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 <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:
generateChangelog(config: LogsmithConfig): Promise<ChangelogResult>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)
}
defineConfig(config: LogsmithConfig): LogsmithConfigTypeScript 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.md
Or use them together in your build scripts:
{
"scripts": {
"release": "logsmith patch && logsmith --output CHANGELOG.md"
}
}
MIT License © 2024-PRESENT Chris Breuer
FAQs
Forge beautiful changelog automatically.
The npm package @stacksjs/logsmith receives a total of 45,247 weekly downloads. As such, @stacksjs/logsmith popularity was classified as popular.
We found that @stacksjs/logsmith demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A critical vm2 sandbox escape can allow untrusted JavaScript to break isolation and execute commands on the host Node.js process.
Research
Five malicious NuGet packages impersonate Chinese .NET libraries to deploy a stealer targeting browser credentials, crypto wallets, SSH keys, and local files.
Security News
pnpm 11 turns on a 1-day Minimum Release Age and blocks exotic subdeps by default, adding safeguards against fast-moving supply chain attacks.