On this page
Manage structured JSONL changelog entries: add, amend, edit, and remap per-commit entries, validate schema and coverage, and generate CHANGELOG.md.
#rlsbl changelog
Structured changelog management using JSONL entries with 3 entry types (feature, fix, breaking). Add and generate CHANGELOG.md from per-commit changelog entries stored in unreleased.jsonl for precise, auditable release notes.
#changelog add
Append a structured changelog entry to the project's unreleased.jsonl file. Each entry includes a human-readable description, an entry type (feature, fix, or breaking), and optional commit hashes linking it to specific changes. The file is auto-committed by default. Use --no-user-facing to mark internal changes that should not appear in the published changelog.
Effect: mutating
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--commits | str | Comma-separated list of commit hashes to associate with this changelog entry | |||
--description | str | Human-readable description of the change, shown in the generated CHANGELOG.md | |||
--type | str | Classification of the change: feature, fix, or breaking (required if user-facing) | |||
--user-facing | bool | True | Mark this entry as user-facing (included in generated CHANGELOG.md output) | ||
--auto-commit | bool | True | Auto-commit unreleased.jsonl after appending the entry | ||
--allow-batch | bool | Auto-create an exclusion if this entry exceeds the commit batch limit |
#changelog generate
Compile all validated JSONL changelog entries into a formatted CHANGELOG.md file. Groups entries by type (features, fixes, breaking changes) under the appropriate version heading, preserving existing changelog content for previous releases. Use --dry-run to preview the generated Markdown output without writing to disk, which is useful for reviewing before committing.
Effect: mutating
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--auto-commit | bool | True | Auto-commit generated CHANGELOG.md and per-version .md files |
#changelog amend
Append a changelog entry to a released version's JSONL file. Temporarily unlocks the read-only file, appends the entry, re-locks it, regenerates CHANGELOG.md, and syncs GitHub Release notes. Use --no-validate-hashes to skip hash validation for old or amended commits.
Effect: mutating
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--version | str | Semver of the already-released version whose JSONL to amend (e.g. 0.39.0) | |||
--commits | str | Comma-separated commit hashes to associate with the amended changelog entry | |||
--id | str | Entry ID (ULID) to select the target entry for amendment | |||
--description | str | Human-readable description for the amended entry in CHANGELOG.md | |||
--type | str | Classification for the amended entry: feature, fix, or breaking (required if user-facing) | |||
--user-facing | bool | True | Mark the amended entry as user-facing (included in CHANGELOG.md output) | ||
--validate-hashes | bool | True | Validate commit hashes via git rev-parse before appending |
#changelog edit
Modify an existing changelog entry in unreleased or released JSONL files. Finds the entry by commit hash or entry ID, applies field changes (type, description, user-facing status), and rewrites the file atomically. For released files, temporarily unlocks the read-only file, regenerates CHANGELOG.md, and syncs GitHub Release notes.
Effect: mutating
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--commits | str | Comma-separated commit hashes identifying the target entry | |||
--id | str | Entry ID (ULID) identifying the target entry to edit in the JSONL file | |||
--type | str | New type value (feature, fix, breaking); also disambiguates multi-entry commits | |||
--description | str | Replacement description text for the matched changelog entry | |||
--user-facing | bool | Set user_facing status on the matched entry (--user-facing to set true, --no-user-facing to set false) | |||
--auto-commit | bool | True | Automatically commit the edited JSONL changelog file to git after modification |
#changelog remap
Remap stale commit hashes in JSONL changelog files using a mapping of old SHAs to new SHAs. Reads the mapping from a file (--map-file), the safegit rewrite journal (--from-journal), or stdin (--stdin). At least one source is required. Auto-commits with Autogenerated trailer.
Effect: mutating
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--map-file | str | Path to a file of 'old_sha new_sha' lines (same format as git's post-rewrite hook) | |||
--from-journal | bool | Read the commit map from safegit's rewrite journal (.git/safegit/rewrite-maps.jsonl) | |||
--stdin | bool | Read the old/new SHA map from stdin (for piping from git's post-rewrite hook) |