changelog generator & diff tool
stormlightlabs.github.io/git-storm/
desertthunder.dev
changelog
changeset
markdown
golang
git
1---
2title: Introduction
3outline: deep
4---
5
6# Introduction
7
8Storm is a CLI that keeps changelog entries close to your code. It grew from a
9few principles:
10
111. **Plain text first.** Every unreleased change is a Markdown file that lives
12 in your repo, making reviews and rebases simple.
132. **Deterministic releases.** Given the same `.changes` directory, Storm will
14 always write the same `CHANGELOG.md` section.
153. **Interactive when helpful, scriptable everywhere.** TUIs exist for reviews
16 and diffs, but every action prints machine-readable summaries for CI.
17
18## Why Storm?
19
20Storm sits between `git log` and `CHANGELOG.md`. It understands conventional
21commits, keeps notes in version control, and prefers deterministic text files
22over generated blobs. The CLI is written in Go, so it ships as a single binary
23that runs anywhere your repository does.
24
25- **Local-first workflow:** no external services or databases.
26- **Deterministic releases:** `storm release` is idempotent and can run in CI.
27- **Composable commands:** each subcommand prints useful summaries for scripts.
28
29## Quick Preview
30
31```sh
32# Extract commits into .changes entries
33storm generate --since v1.2.0 --interactive
34
35# Review pending notes
36storm unreleased review
37
38# Cut a new release and update package.json
39storm release --bump minor --toolchain package.json --tag
40```
41
42Need the details? Head to the [Quickstart](/quickstart) for a guided flow or
43read the [manual](/manual) for every flag and exit code.
44
45## Architecture Overview
46
47```sh
48.git/
49.changes/
50CHANGELOG.md
51```
52
53- `storm generate` and `storm unreleased add` populate `.changes/`.
54- `storm check` and your CI ensure nothing merges without an entry.
55- `storm release` merges the queue into `CHANGELOG.md`, optionally creates a
56tag, and can update external manifests.
57
58## Toolchain-aware versioning
59
60The bump and release commands understand common ecosystem manifests:
61
62| Manifest | Alias | Notes |
63| -------- | ----- | ----- |
64| `Cargo.toml` | `cargo`, `rust` | Updates `[package]` version. |
65| `pyproject.toml` | `pyproject`, `python`, `poetry` | Supports `[project]` and `[tool.poetry]`. |
66| `package.json` | `npm`, `node`, `package` | Edits the top-level `version` field. |
67| `deno.json` | `deno` | Updates the root `version`. |
68
69Pass specific paths or the literal `interactive` to launch the toolchain picker
70TUI.
71
72## TUIs everywhere
73
74Storm shares a consistent palette (`internal/style`) across Bubble Tea
75experiences:
76
77- **Commit selector** for `storm generate --interactive`.
78- **Unreleased review** for curating `.changes` entries.
79- **Diff viewer** for `storm diff` with split/unified modes.
80- **Toolchain picker** accessible via `--toolchain interactive`.
81
82Each interface supports familiar Vim-style navigation (↑/↓, g/G, space to
83select, `q` to quit) and degrades gracefully when no TTY is available.
84
85## Suggested Workflow
86
871. Developers add `.changes` entries alongside feature branches.
882. Pull requests run `storm check --since <last-release>`.
893. Release engineers run `storm generate` (if needed) then `storm release`.
904. CI tags the release and publishes artifacts.
91
92Need concrete steps? See the [Quickstart](/quickstart) or jump to the
93[manual](/manual).