Quick Start

# Install directly from GitHub (recommended until published to PyPI)
pip install git+https://github.com/JToSound/LogForge.git
cd your-repo
export OPENAI_API_KEY=sk-...
gitlog generate

That's it. Your CHANGELOG.md is ready. 🎉

5s Demo

Below is a very short demo that shows gitlog generate producing a changelog in under 5 seconds on small repos.

Features

• 🤖 Two-layer classification — rule engine (zero API cost) + LLM batch fallback
• 🌍 Multilingual output — English, Traditional Chinese, Simplified Chinese, Japanese
• 📄 Multiple formats — Markdown (Keep-a-Changelog), JSON, HTML, Twitter drafts
• 🔗 GitHub integration — auto-generates PR/issue/commit links
• ⚡ Batch LLM calls — never call the LLM in a loop; respects token budgets
• 🔄 Fallback chain — LLM failure → rule engine, never interrupts the flow
• 🧩 CI/CD ready — GitHub Actions workflow included out of the box
• 🏠 Local inference — Ollama support for fully private generation

Installation

# Recommended: with uv
uv tool install gitlog

# Or pip
pip install gitlog

Requirements: Python 3.11+, Git

Usage

# Generate full CHANGELOG
gitlog generate

# From a specific version
gitlog generate --since v1.2.0

# HTML report
gitlog generate --format html

# Traditional Chinese output
gitlog generate --lang zh-TW

# Use a local Ollama model (no API key needed)
gitlog generate --model ollama/llama3

# Preview in terminal without writing a file
gitlog generate --dry-run

# Compare two versions
gitlog diff v1.0.0 v1.1.0

# Generate Twitter/X announcement
gitlog tweet

# ASCII commit statistics
gitlog stats

# Interactive setup
gitlog init

Configuration

Create a .gitlog.toml in your repo root (or run gitlog init):

[gitlog]
llm_provider = "openai"
model = "gpt-4o-mini"
language = "en"
format = "markdown"
output_file = "CHANGELOG.md"
project_description = "A developer tool for..."
exclude_patterns = ["^chore\\(deps\\)", "^Merge branch"]
group_by_scope = true
max_commits_per_group = 20

[gitlog.github]
repo = "owner/repo"

Full Configuration Reference

GitHub Actions Integration

Add to your release workflow:

- name: Generate Changelog
  uses: JToSound/LogForge/.github/workflows/release.yml@main
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Or use the included release.yml which automatically:

1. Builds and publishes to PyPI on tag push
2. Generates the changelog using gitlog itself
3. Creates a GitHub Release with the generated notes

Supported LLM Providers

License

MIT © gitlog contributors