changelog generator & diff tool
stormlightlabs.github.io/git-storm/
desertthunder.dev
changelog
changeset
markdown
golang
git
1---
2title: Storm CLI Manual
3---
4
5# NAME
6
7**storm** is a git powered aware changelog manager for Go projects.
8
9## SYNOPSIS
10
11```text
12storm [--repo <path>] [--output <file>] <command> [flags]
13```
14
15## DESCRIPTION
16
17Storm keeps unreleased notes in `.changes/*.md`, promotes them into
18`CHANGELOG.md`, and offers TUIs for reviewing diffs and entries. The binary
19is composed of self-contained subcommands that chain well inside scripts
20or CI jobs.
21
22### GLOBAL FLAGS
23
24| Flag | Description |
25| ----------------------- | -------------------------------------------------------- |
26| `--repo <path>` | Working tree to operate on (default: current directory). |
27| `-o`, `--output <file>` | Target changelog (default: `CHANGELOG.md`). |
28
29### COMMANDS
30
31#### `storm bump`
32
33Calculate the next semantic version by inspecting `CHANGELOG.md`.
34
35```text
36storm bump --bump <major|minor|patch> [--toolchain value...]
37```
38
39##### Flags
40
41| Flag | Description |
42| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
43| `--bump <type>` _(required)_ | Which semver component to increment. |
44| `--toolchain <value>` | Update language manifests (`Cargo.toml`, `pyproject.toml`, `package.json`, `deno.json`). |
45| | Accepts explicit paths, type aliases like `cargo`/`npm`, or the literal `interactive` to launch a picker TUI. |
46
47#### `storm release`
48
49Promote `.changes/*.md` into the changelog and optionally tag the repo.
50
51```text
52storm release (--version X.Y.Z | --bump <type>) [flags]
53```
54
55##### Flags
56
57| Flag | Description |
58| --------------------- | ----------------------------------------------------------------------------------- |
59| `--version <X.Y.Z>` | Explicit version for the new changelog entry. |
60| `--bump <type>` | Derive the version from the previous release (mutually exclusive with `--version`). |
61| `--date <YYYY-MM-DD>` | Override the release date (default: today). |
62| `--clear-changes` | Remove `.changes/*.md` files after a successful release. |
63| `--dry-run` | Render a preview without touching any files. |
64| `--tag` | Create an annotated git tag containing the release notes. |
65| `--toolchain <value>` | Update manifest files just like in `storm bump`. |
66| `--output-json` | Emit machine-readable JSON instead of styled text. |
67
68#### `storm generate`
69
70Create `.changes/*.md` files from commit history, with optional TUI review.
71
72```text
73storm generate <from> <to>
74storm generate --since <tag> [to]
75```
76
77##### Flags
78
79| Flag | Description |
80| --------------------- | -------------------------------------------------- |
81| `-i`, `--interactive` | Open a commit selector TUI for choosing entries. |
82| `--since <tag>` | Shortcut for `<from>`; defaults `<to>` to `HEAD`. |
83| `--output-json` | Emit machine-readable JSON instead of styled text. |
84
85#### `storm diff`
86
87Side-by-side or unified diff with TUI navigation.
88
89```text
90storm diff <from>..<to> [flags]
91storm diff <from> <to> [flags]
92```
93
94| Flag | Description |
95| ------------------------------- | ----------------------------------------------------- |
96| `-f`, `--file <path>` | Restrict the diff to a single file. |
97| `-e`, `--expanded` | Show all unchanged lines instead of compressed hunks. |
98| `-v`, `--view <split\|unified>` | Rendering style (default: split). |
99
100#### `storm check`
101
102Verify every commit in a range has a corresponding unreleased entry.
103
104```text
105storm check <from> <to>
106storm check --since <tag> [to]
107```
108
109| Flag | Description |
110| --------------- | ---------------------------------------------------------- |
111| `--since <tag>` | Start range at the provided tag and default end to `HEAD`. |
112
113Non-zero exit status indicates missing entries. Messages containing
114`[nochanges]` or `[skip changelog]` are ignored.
115
116#### `storm unreleased`
117
118Manage `.changes` entries directly.
119
120##### `add`
121
122```text
123storm unreleased add --type <kind> --summary <text> [--scope value]
124```
125
126| Flag | Description |
127| --------------------------------------------------- | ------------------------------------------- |
128| `--type <added\|changed\|fixed\|removed\|security>` | Entry category. |
129| `--summary <text>` | Short human readable note. |
130| `--scope <value>` | Optional component indicator (e.g., `cli`). |
131
132##### `list`
133
134```text
135storm unreleased list [--json]
136```
137
138| Flag | Description |
139| -------- | -------------------------------------------------- |
140| `--json` | Emit machine-readable JSON instead of styled text. |
141
142##### `partial`
143
144```text
145storm unreleased partial <commit-ref> [flags]
146```
147
148| Flag | Description |
149| ------------------ | --------------------------------------------------- |
150| `--type <value>` | Override the inferred type from the commit message. |
151| `--summary <text>` | Override the inferred summary. |
152| `--scope <value>` | Optional component indicator. |
153
154##### `review`
155
156```text
157storm unreleased review
158```
159
160Launch a Bubble Tea TUI for editing and deleting entries before release.
161Requires a TTY; fall back to `storm unreleased list` otherwise.
162
163#### `storm version`
164
165Print the current build’s version string.
166
167## FILES
168
169- `.changes/` — queue of unreleased entries created by `storm generate` or `storm unreleased add`.
170- `CHANGELOG.md` — Keep a Changelog-compatible file updated by `storm release`.
171
172## SEE ALSO
173
174`CHANGELOG.md`, [Keep a Changelog](https://keepachangelog.com), semantic versioning at [semver.org](https://semver.org).