CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-generate-changelog

Generate a changelog from git commits using structured commit message format.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Generate Changelog

Generate Changelog is a Node.js library and CLI tool that automatically generates changelog files from git commit messages. It requires commit messages to follow a specific format (type(category): description [flags]) and supports both programmatic usage and command-line execution for automated changelog generation in CI/CD workflows.

Package Information

  • Package Name: generate-changelog
  • Package Type: npm
  • Language: JavaScript (Node.js)
  • Installation: npm install generate-changelog

Core Imports

const { generate } = require('generate-changelog');

ES6 modules (if supported):

import { generate } from 'generate-changelog';

Basic Usage

Programmatic API

const { generate } = require('generate-changelog');

// Generate a patch changelog
generate({ patch: true, repoUrl: 'https://github.com/user/repo' })
  .then(function (changelog) {
    console.log(changelog);
  })
  .catch(function (err) {
    console.error(err);
  });

CLI Usage

# Generate a patch changelog
generate-changelog -p

# Generate a minor changelog with excluded commit types
generate-changelog -m --exclude "chore,style"

# Generate changelog for specific tag range
generate-changelog --tag "v1.0.0..v1.1.0"

Architecture

Generate Changelog is built around several key modules:

  • Main API: Core generate() function that orchestrates the changelog generation process
  • Git Module: Extracts and parses commit messages from git history
  • Package Module: Reads package.json for version information and repository URLs
  • Writer Module: Formats commit data into markdown changelog format
  • File Module: Handles file system operations for reading and writing
  • CLI Module: Command-line interface built with Commander.js

Capabilities

Changelog Generation

Core functionality to generate markdown changelog content from git commits.

/**
 * Generate the changelog.
 * @param {Object} options - generation options
 * @param {Boolean} options.patch - whether it should be a patch changelog
 * @param {Boolean} options.minor - whether it should be a minor changelog
 * @param {Boolean} options.major - whether it should be a major changelog
 * @param {String} options.repoUrl - repo URL that will be used when linking commits
 * @param {Array} options.exclude - exclude listed commit types (e.g. ['chore', 'style', 'refactor'])
 * @param {String} options.tag - generate from specific tag or range (e.g. 'v1.2.3' or 'v1.2.3..v1.2.4')
 * @param {Boolean} options.allowUnknown - allow unknown commit types
 * @returns {Promise<String>} the newline separated changelog string
 */
function generate(options);

Usage Examples:

const { generate } = require('generate-changelog');

// Generate patch changelog
const patchChangelog = await generate({ patch: true });

// Generate minor changelog with repo links
const minorChangelog = await generate({ 
  minor: true, 
  repoUrl: 'https://github.com/user/repo' 
});

// Generate changelog excluding certain commit types
const filteredChangelog = await generate({
  major: true,
  exclude: ['chore', 'style', 'refactor']
});

// Generate changelog for specific tag range
const rangeChangelog = await generate({
  tag: 'v1.0.0..v1.1.0',
  repoUrl: 'https://github.com/user/repo'
});

CLI Interface

Command-line interface for generating changelogs directly from terminal.

# CLI Options
generate-changelog [options]

Options:
  -h, --help             output usage information
  -V, --version          output the version number
  -p, --patch            create a patch changelog
  -m, --minor            create a minor changelog
  -M, --major            create a major changelog
  -t, --tag <range>      generate from specific tag or range (e.g. v1.2.3 or v1.2.3..v1.2.4)
  -x, --exclude <types>  exclude selected commit types (comma separated)
  -f, --file [file]      file to write to, defaults to ./CHANGELOG.md, use - for stdout
  -u, --repo-url [url]   specify the repo URL for commit links, defaults to checking the package.json
  -a, --allow-unknown    allow unknown commit types

CLI Usage Examples:

# Generate patch changelog and write to CHANGELOG.md
generate-changelog -p

# Generate minor changelog with custom output file
generate-changelog -m -f RELEASE_NOTES.md

# Generate changelog excluding specific types
generate-changelog -M --exclude "chore,style,test"

# Generate changelog for tag range with custom repo URL
generate-changelog --tag "v1.0.0..v2.0.0" --repo-url "https://github.com/user/repo"

# Output changelog to stdout
generate-changelog -p -f -

Commit Message Format

Generate Changelog requires commit messages to follow this specific format:

type(category): description [flags]

Supported Commit Types

  • breaking - Breaking Changes
  • build - Build System / Dependencies
  • ci - Continuous Integration
  • chore - Chores
  • docs - Documentation Changes
  • feat - New Features
  • fix - Bug Fixes
  • other - Other Changes
  • perf - Performance Improvements
  • refactor - Refactors
  • revert - Reverts
  • style - Code Style Changes
  • test - Tests

Commit Format Examples

feat(auth): add OAuth2 login support
fix(parser): handle malformed JSON responses
breaking(api): remove deprecated endpoints [breaking]
docs(readme): update installation instructions

Flags

Optional flags can be added in square brackets:

  • [breaking] - Marks any commit type as a breaking change

Error Handling

The library handles various error conditions:

  • No package.json found: Throws Error('valid package.json not found')
  • No commits found: Throws Error('no commits found')
  • Invalid commit format: Commits that don't match the pattern are filtered out
  • File system errors: Missing files return empty strings instead of throwing

Types

// Options object for generate() function
interface GenerateOptions {
  patch?: boolean;          // Generate patch changelog
  minor?: boolean;          // Generate minor changelog  
  major?: boolean;          // Generate major changelog
  repoUrl?: string;         // Repository URL for commit links
  exclude?: string[];       // Commit types to exclude
  tag?: string;             // Tag or range specification
  allowUnknown?: boolean;   // Allow unknown commit types
  file?: string;            // Output file path (used by CLI)
}

// Parsed commit object structure
interface ParsedCommit {
  hash: string;             // Full commit hash
  subject: string;          // Parsed subject line
  body: string;             // Commit body
  type: string;             // Commit type (feat, fix, etc.)
  category: string;         // Commit category from parentheses
}

// Package.json structure (subset)
interface PackageInfo {
  name: string;             // Package name
  version: string;          // Current version
  repository?: {            // Repository information
    type: string;
    url: string;
  };
}

docs

index.md

tile.json