A tiny TUI and CLI to build CHANGELOGs from your git history. Browse your git graph on the left, pick "anchor" commits that mark minor releases, and watch a live preview on the right. Press Enter to write CHANGELOG.md. Or, use the non-interactive CLI in scripts.

• Left pane: git log graph with htop-style scrolling
• Right pane: live preview of the generated CHANGELOG
• Anchor selection -> versions: 0.1.0, 0.2.0, ... with evenly spaced patches in between
• Colorful highlighting, persistent help bars, comfy terminal UX
• Headless CLI mode for CI/scripts

Works best on macOS/Linux terminals. Windows users: try WSL.

• Changelogger
  • Demo
  • Install
  • Usage
    • Interactive (TUI)
    • Non-interactive (CLI for scripts/CI)
  • Versioning algorithm
  • Output format
  • Library (programmatic)
  • UI details
  • Requirements
  • Documentation
  • Troubleshooting
  • Contributing
  • License

Gemfile:

gem "changelog-builder"

Then:

bundle install

Or install globally:

gem install changelog-builder

From a git repository (or pass a repo path/URL):

# Current repo
changelogger

# Local path
changelogger ../some_dir/project

# GitHub slug
changelogger rails/rails

# Full URL
changelogger https://github.com/rails/rails.git
changelogger [email protected]:rails/rails.git

• Move (left): Up/Down or j/k
• Select anchors: Space
• Toggle fit: f (show entire selected commit block if it fits)
• Refresh graph: r
• Resize split: < and >
• Switch focus: Tab / Shift-Tab
• Scroll preview (right): Up/Down, PgUp/PgDn, g/G
• Generate: Enter (writes CHANGELOG.md)
• Quit: q or ESC (exits quietly)
• z: toggle zebra striping
• The frame titles show which repo you’re working in:
  • Left title: Graph — <repo_name> [<branch>@<short_sha>*], where * indicates uncommitted changes
  • Right title: Preview — <remote slug> (e.g., owner/repo) or repo name if no remote
• Visual separators:
  • A thin dotted line appears at commit boundaries (without overwriting the graph)
  • Zebra striping per commit block helps scanning; toggle with z

The .graph cache is regenerated automatically; use r to refresh.

Generate a CHANGELOG without the TUI. You must provide at least 2 anchors (SHAs, tags, or branches). REPO can be a local path, GitHub slug, or git URL.

# Write CHANGELOG.md in current repo
changelogger --generate --anchors v1.0.0,v1.1.0

# Write to custom file
changelogger --generate --anchors abc1234,def5678 -o HISTORY.md

# Run against another repo (local path)
changelogger --generate --anchors v1.0.0,v1.2.0 ../some/project

# Run against a GitHub repo (slug or URL)
changelogger --generate --anchors v7.0.0,main rails/rails
changelogger --generate --anchors a1b2c3d,deadbeef https://github.com/user/repo.git

# Print to stdout (no file)
changelogger --generate --anchors v1.0.0,v1.1.0 --dry-run

Options:

• --generate, -g: Non-interactive mode
• --anchors x,y,z: Anchors (2+). Each token can be a full/short SHA, tag, or branch name
• --output PATH, -o PATH: Output file (default: CHANGELOG.md)
• --major N: Major version (default 0)
• --minor-start N: Minor start index (default 1 -> 0.1.0, 0.2.0, ...)
• --base-patch N: Patch spacing base (default 10)
• --dry-run: Print to stdout

Exit codes:

• 0: Success
• 1: General error
• 2: Invalid arguments (e.g., insufficient anchors)

"Semantic-ish" mapping:

• Major stays 0 by default (configurable)
• Minor increments per anchor: 0.1.0, 0.2.0, 0.3.0, ...
• In-between commits get patches spaced over 1..base (default 10):
  • patches[i] = round((i+1) * base / (k+1)) with monotonic fixups
  • 1 between -> 0.1.5
  • 2 between -> 0.1.3, 0.1.7
  • 3 between -> 0.1.3, 0.1.5, 0.1.8

Each selected commit (anchors and in-between) gets:

• Section: "## [x.y.z] - YYYY-MM-DD"
• Bullet: "- (<short_sha>)"
• Commit body is included and indented
• A top "## [Unreleased]" section is always present

Use the building blocks directly:

require "changelogger"
# or just require "changelogger"

commits = Changelogger::Git.commits
anchors = ["abc1234", "def5678"] # full or short SHAs, or resolve with `git rev-parse`

# Preview as a string:
puts Changelogger::ChangelogGenerator.render(commits, anchors, base_patch: 12)

# Or write:
Changelogger::ChangelogGenerator.generate(commits, anchors, path: "CHANGELOG.md", major: 1, minor_start: 0)

Note:

• require "changelogger" only loads the module/version (no TUI).
• For the TUI specifically: require "changelogger/tui".

• Side-by-side layout with color highlighting
• Help bars at the top of each pane
• htop-like scrolling in the graph pane
• "Fit selected commit" avoids cutting blocks at the bottom (toggle with f)
• .graph is auto-regenerated; press r to refresh

• Ruby 3.0+
• Git installed
• POSIX terminal (colors recommended)
• Linux/macOS tested; Windows via WSL recommended

Code is covered with YARD notation. All docs could be accessed from separate page https://unurgunite.github.io/changelog-builder_docs/

• Tab doesn’t switch focus: try Shift-Tab; ensure TERM is set (e.g., xterm-256color)
• No colors: falls back to bold/standout
• Not a git repo: pass a repo path/slug/URL
• Cancel in TUI: exits quietly (no "not enough commits" message)

PRs welcome. Please keep changes focused and include reproduction steps or a short clip for UI tweaks.

MIT © 2021–present unurgunite, SY573M404