changelog generator & diff tool
stormlightlabs.github.io/git-storm/
desertthunder.dev
changelog
changeset
markdown
golang
git
1---
2title: Quickstart
3outline: deep
4---
5
6# Quickstart
7
8This walkthrough gets you from zero to a published changelog entry in a few
9minutes. It mirrors the default workflow baked into the CLI.
10
11## 1. Install the CLI
12
13```sh
14go install github.com/stormlightlabs/git-storm/cmd/storm@latest
15```
16
17Verify the binary is available:
18
19```sh
20storm version
21```
22
23## 2. Capture unreleased changes
24
25Create a `.changes` entry manually or generate them from commits.
26
27### Option A — Manual entry
28
29```sh
30storm unreleased add \
31 --type added \
32 --scope cli \
33 --summary "Add bump command"
34```
35
36### Option B — From git history
37
38```sh
39storm generate --since v1.2.0 --interactive
40```
41
42Use the commit selector TUI to pick which commits become entries. Storm writes
43Markdown files such as `.changes/2025-03-01-add-bump-command.md`.
44
45## 3. Review pending entries
46
47```sh
48storm unreleased review
49```
50
51The Bubble Tea UI lets you edit summaries, delete noise, or mark entries as
52ready. In non-interactive environments, fall back to
53`storm unreleased list --json`.
54
55## 4. Dry-run a release
56
57```sh
58storm release --bump patch --dry-run
59```
60
61This prints the new `CHANGELOG` section without modifying files. When the
62output looks right, re-run without `--dry-run`.
63
64## 5. Publish and tag
65
66```sh
67storm release --bump patch --toolchain package.json --tag
68```
69
70- `--bump patch` derives the next version from the previous release.
71- `--toolchain package.json` keeps your npm manifest in sync.
72- `--tag` creates an annotated git tag containing the release notes.
73
74Follow up with standard git commands:
75
76```sh
77git add CHANGELOG.md package.json .changes
78git commit -m "Release v$(storm bump --bump patch)"
79git push origin main --tags
80```
81
82## 6. Enforce entries in CI (optional)
83
84```sh
85storm check --since v1.2.0
86```
87
88The command exits non-zero when commits are missing `.changes` files, making it
89ideal for pre-merge checks.
90
91## Next steps
92
93- Skim the [Introduction](/introduction) to understand the design.
94- Explore every flag in the [manual](/manual).