Theme
Aa
← man.tcos.us gopher root · man.tcos.us
lu: · ·
HEE-GEN-CHANGELOG(1)               HEE Tools               HEE-GEN-CHANGELOG(1)

NAME
       hee-gen-changelog  -  render  CHANGELOG.md  from  the  repo's  own merge
       history

SYNOPSIS
              hee-gen-changelog [PATH]                 dry run: print what [Unreleased] would become
              hee-gen-changelog [PATH] --write         write it into CHANGELOG.md (created if absent)
              hee-gen-changelog [PATH] --release VER   turn [Unreleased] into "## [VER] - today", then --write
              hee-gen-changelog [PATH] --since REF|DATE   history window (default: the newest dated header)
              hee-gen-changelog help

DESCRIPTION
              The [Unreleased] block, from conventional-commit subjects; nothing typed.

                Every merge to main is a Conventional Commit with its PR number
                (rule 8: `type(scope): description (#N)`). That is already a changelog;
                this renders it in Keep a Changelog form so nobody types it twice or
                forgets it. Operator, 2026-09-05: "keep a nice change log with the
                updates."

                Grouping: feat -> Added; fix -> Fixed; docs -> Documentation;
                perf -> Performance; a `!` or BREAKING CHANGE -> Breaking; chore,
                refactor, ci, build, test, style, lint, ops -> Changed; anything else
                -> Other. Each line: date, bold scope, the description verbatim, and a
                real link to the PR. The window starts at the newest `## [x] - DATE`
                header in CHANGELOG.md (or --since); merges are skipped.

                DRY RUN IS THE DEFAULT -- the same rule as hee-gen-manpages, for the
                same reason (issue 464). --write replaces only the [Unreleased] block;
                released sections are never touched. --release VER renames the block
                to a dated version header and starts a new empty [Unreleased].

                Because a PR cannot know its own squash subject in advance, the file
                is regenerated AFTER merges, as a chore PR -- the same cadence as the
                gopher man tree. `hee-gen-changelog` with no flags is the check: its
                first line is a status line saying whether the committed [Unreleased]
                block still matches a fresh render.

                That line used to be documented here as "empty output means the file is
                current", which was never true -- a dry run always printed the whole
                rendered block, so nothing could tell current from stale without diffing
                by hand. `hee repo-refresh regen` needs that answer, so the tool now
                gives it rather than having its caller re-derive it (rule 15).

EXIT STATUS
              0 OK (dry run rendered, or written)   2 CRITICAL (not a git repo, no window)   3 UNKNOWN

EXAMPLES
              hee gen-changelog

              A bare run is a dry run: it prints the status line and what [Unreleased]
              would become, and writes nothing. Not marked "# ci": it reads full git
              history and tags, which a shallow CI checkout does not have (a failed git
              call exits nonzero), so it is not self-contained on a runner. --write and
              --release change CHANGELOG.md and are likewise unmarked.

                                                           HEE-GEN-CHANGELOG(1)