Logsmith

Features

Quick Start

CLI Usage

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

### GitHub Action

Use Logsmith in your GitHub workflows:

```yaml
name: Generate Changelog
on:
  push:
    tags: ['v*']

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:

      - uses: actions/checkout@v4

        with:
          fetch-depth: 0

      - uses: stacksjs/[email protected]

        with:
          output: 'CHANGELOG.md'
          theme: 'github'

CLI Commands

Main Command

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)
- `--show-author-email` - Print author email addresses in the changelog (hidden by default)

**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)

Configuration

import { defineConfig } from 'logsmith'

export default defineConfig({
  output: 'CHANGELOG.md',

  // Changelog options
  hideAuthorEmail: true,
  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,
})

Configuration Options

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>
  }
}

Conventional Commits

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

feat!: remove deprecated API endpoints
feat: add new feature

BREAKING CHANGE: The old API has been removed

Output Formats

Markdown (Default)

### 🚀 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]>

JSON Format

{
  "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
  }
}

HTML Format

API Reference

generateChangelog(config: LogsmithConfig): Promise<ChangelogResult>

interface ChangelogResult {
  content: string // Generated changelog content
  outputPath?: string // Path where changelog was written (if output option used)
}

defineConfig(config: LogsmithConfig): LogsmithConfig

Integration with Version Bumping

# First bump the version
bunx bumpx patch

# Then generate changelog
logsmith --output CHANGELOG.md

{
  "scripts": {
    "release": "logsmith patch && logsmith --output CHANGELOG.md"
  }
}

Credits

Sponsors

License