@lglen/awk-changelog-tool

Lightning-fast changelog generator from git history. Supports PR descriptions via GitHub CLI.

Features

• Extremely fast — Uses git log --numstat in a single pass then pipe to awk
• Markdown output — Clean, readable changelogs with commit stats (files changed, lines added/removed)
• PR descriptions — Optional integration with GitHub CLI to include pull request descriptions on merge, squash, and rebase commits
• CLI + API — Use as a command-line tool or dev dependency
• Zero setup required — Use directly through npx, or 'awkch -d' as a dev dependency/global install

Installation

As a project dependency (recommended for build pipelines)

npm install --save-dev @lglen/awk-changelog-tool

Then add it to your package.json scripts:

{
  "scripts": {
    "changelog": "awkch --default",
    "changelog:pr": "awkch --all"
  }
}

Now npm run changelog and npm run changelog:pr work immediately — npm auto-resolves awkch from node_modules/.bin.

Globally

npm install -g @lglen/awk-changelog-tool

Then awkch is available anywhere on your PATH.

On the fly (no install)

npx @lglen/awk-changelog-tool

npx fetches and caches the package automatically. Great for one-off usage.

CLI Usage

Basic changelog

Generate a changelog from the first commit to HEAD:

awkch

From a specific ref:

awkch 3c06d42

awkch HEAD~49

HEAD~49 includes exactly the last 50 commits (when the repository has at least 50 commits). The starting ref is inclusive.

Write to a file:

awkch -o CHANGELOG.md

With PR descriptions

Requires the GitHub CLI (gh) installed and authenticated.

Works with every merge strategy:

• Merge commits and squash merges are matched through the PR's merge commit (and the (#N) marker GitHub adds to the title).
• Rebase merges are matched by commit message + order: rebase rewrites SHAs but keeps messages, so each PR's gh pr view --json commits messages are joined to the branch's commits. One gh pr view per PR that isn't already matched by a merge commit (rebase-merged, open, or a feature branch viewed before its merge commit lands). The description is placed above the top commit of the group. Only ambiguity: two PRs sharing an identical commit message.

awkch --pr

In an interactive terminal, --pr shows an in-place progress display while it fetches PR details, including elapsed time, average PRs per second, and an ETA. When writing to an existing awkch changelog (for example, awkch --all), the CLI uses its newest recorded commit as the checkpoint, adds only newer commits, and limits PR detail lookups to PRs merged since that checkpoint. Existing entries are retained. Pass --fresh to disable incremental mode and rebuild the full changelog in place, or pass an explicit starting ref. You can also remove or rename the output file to force a full rebuild.

See awkch --help for command-line examples, including limiting the output to recent commits and writing PR descriptions to a file.

Options

| Option | Description | |--------|-------------| | -V, --version | Show version | | -h, --help | Show help | | -o, --output <file> | Write to file (default: stdout) | | -p, --pr | Include PR descriptions (requires gh CLI) | | -d, --default | Set output file to CHANGELOG.md | | -a, --all | Shorthand for --pr --default | | -f, --fresh | Disable incremental mode and rewrite the changelog from scratch | | -n, --no-email | Strip email addresses from author names |

Programmatic API available through npm install

import { generateChangelog, generateChangelogWithPRs } from '@lglen/awk-changelog-tool';

// Basic changelog as a string
const md = generateChangelog({ since: 'HEAD~10' });
console.log(md);

// Changelog with PR descriptions
const result = generateChangelogWithPRs({ since: '3c06d42' });
console.log(result.changelog);
// result.prCount → number of PR descriptions included

Original Bash Scripts

The original awk-based scripts are preserved in bash/ for users who prefer them:

• bash/git-changelog.sh — Basic changelog using awk
• bash/git-changelog-pr.sh — Changelog with PR descriptions for merge and squash commits using awk + jq (via bundled node-jq) + gh (rebase merges need the Node CLI)

To use them directly:

./node_modules/@lglen/awk-changelog-tool/bash/git-changelog.sh

Requirements

• Node.js >= 18
• git (for reading history)
• gh CLI (optional, for PR descriptions)

jq — Bundled via node-jq npm package (no system install needed), ran in bash using jq.mjs

Tests

Run npm test for the unit and package-install integration tests. The package integration test packs the distributable tarball, installs it in a temporary project, and smoke-tests both the awkch CLI and programmatic API. Run only that test with npm run test:package; it requires npm and access to the package registry unless dependencies are already cached. Run npm run test:coverage to execute the unit suites with line/branch/function coverage thresholds.

License

MIT

Example Changelog

From commit c406c3935f8429db809edd1262230be3e132303d (2026-07-23 06:07:52 -0700)

6 commit(s), 1 PR(s) matched

cd69d7d — Merge pull request #1 from LaishGlenberg:lg/feat/add-changelog

| Field | Value | |-------|-------| | Hash | cd69d7d06216baab6caf8ec417f7a9b69b0845b4 | | Date | Thu, 23 Jul 2026 14:20:20 | | Author | lglen [email protected] | | Lines | +0 / −0 | | Files | | | Refs | HEAD -> main, origin/main, origin/HEAD | | Pull Request | #1 |

Commit Message

chore: generate changelog

Pull Request Description

## What & Why

- Generate a changelog for the repo using the awkch tool to demo the tool

## Changes

- Add changelog.md, update gitignore

## Notes

- Adding as a pr to demo the pr tool next

3da00e5 — chore: generate changelog

| Field | Value | |-------|-------| | Hash | 3da00e5ee2a0e815c0b45ffc02c88c92166ce081 | | Date | Thu, 23 Jul 2026 14:14:20 | | Author | lglen [email protected] | | Lines | +54 / −1 | | Files | .gitignore, CHANGELOG.md | | Refs | origin/lg/feat/add-changelog, lg/feat/add-changelog |

2c2081c — refactor: shorten name to awkch

| Field | Value | |-------|-------| | Hash | 2c2081caaf43f3811c0dd4bfcf9dcd40c715439d | | Date | Thu, 23 Jul 2026 13:43:30 | | Author | lglen [email protected] | | Lines | +17 / −17 | | Files | README.md, bin/awk-changelog.js, package.json |

bb7f007 — feat: update readme

| Field | Value | |-------|-------| | Hash | bb7f007aee4718bcfade34ca5cfbff3990e54555 | | Date | Thu, 23 Jul 2026 13:37:49 | | Author | lglen [email protected] | | Lines | +26 / −1 | | Files | README.md |

9935259 — chore: Scaffold npm package repository, add apis, docs, tests

| Field | Value | |-------|-------| | Hash | 9935259f689b498e6a5eec3818038868eaa49241 | | Date | Thu, 23 Jul 2026 13:27:15 | | Author | lglen [email protected] | | Lines | +841 / −8 | | Files | .gitignore, LICENSE, README.md, git-changelog-pr.sh => bash/git-changelog-pr.sh, git-changelog.sh => bash/git-changelog.sh, bin/awk-changelog.js, package-lock.json, package.json, src/changelog-pr.js, src/changelog.js, src/index.js, src/utils.js, test/basic.test.js |

c406c39 — chore: initial commit with both bash scripts (regular and regular + pr descriptions)

| Field | Value | |-------|-------| | Hash | c406c3935f8429db809edd1262230be3e132303d | | Date | Thu, 23 Jul 2026 13:07:52 | | Author | lglen [email protected] | | Lines | +284 / −0 | | Files | git-changelog-pr.sh, git-changelog.sh, package.json |