or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-conventional-changelog-cli

Generate a changelog from git metadata.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/conventional-changelog-cli@5.0.x

To install, run

npx @tessl/cli install tessl/npm-conventional-changelog-cli@5.0.0

index.mddocs/

Conventional Changelog CLI

Conventional Changelog CLI is a command-line tool that generates changelogs from git metadata. It parses commit messages following conventional commit standards and produces formatted changelog files, supporting various presets and configuration options for different project workflows.

Package Information

  • Package Name: conventional-changelog-cli
  • Package Type: npm
  • Language: JavaScript (ES Module)
  • Installation: npm install -g conventional-changelog-cli
  • Node.js Requirements: >= 18

Core Imports

The tool is primarily used as a global CLI command:

conventional-changelog [options]

For programmatic usage, import the underlying conventional-changelog library:

import conventionalChangelog from "conventional-changelog";

CommonJS:

const conventionalChangelog = require("conventional-changelog");

Basic Usage

# Generate changelog using angular preset, writing to CHANGELOG.md
conventional-changelog -p angular -i CHANGELOG.md -s

# Generate entire changelog history (overwrite existing)
conventional-changelog -p angular -i CHANGELOG.md -s -r 0

# Output to stdout
conventional-changelog -p angular

# Use custom config and context
conventional-changelog -p angular -n config.js -c context.json

Architecture

Conventional Changelog CLI is built on several key components:

  • CLI Layer: Command-line interface (conventional-changelog-cli) that parses arguments and orchestrates changelog generation
  • Core Engine: Main changelog generation logic (conventional-changelog package) that coordinates the entire process
  • Preset System: Configurable commit parsing rules for different project styles (angular, atom, etc.)
  • Git Integration: Raw commit extraction and processing from git repositories
  • Template Engine: Customizable changelog formatting and output generation

The CLI tool acts as a convenient wrapper around the core conventional-changelog package, making it accessible from command line while supporting both file-based and programmatic configuration.

Programmatic API

For programmatic usage, the underlying conventional-changelog function is available:

/**
 * Generate changelog stream programmatically
 * @param options - Configuration options including preset, releaseCount, etc.
 * @param context - Template context with version info, links, etc.
 * @param gitRawCommitsOpts - Git commit extraction options
 * @param parserOpts - Commit parsing options
 * @param writerOpts - Changelog writing options
 * @returns Readable stream of generated changelog
 */
function conventionalChangelog(
  options?: ChangelogOptions,
  context?: TemplateContext,
  gitRawCommitsOpts?: GitRawCommitsOptions,
  parserOpts?: ParserOptions,
  writerOpts?: WriterOptions
): ReadableStream;

interface ChangelogOptions {
  preset?: string;
  releaseCount?: number;
  skipUnstable?: boolean;
  outputUnreleased?: boolean;
  pkg?: { path?: string };
  append?: boolean;
  lernaPackage?: string;
  tagPrefix?: string;
  warn?: (message: string) => void;
  debug?: (message: string) => void;
}

Programmatic Usage Example:

import conventionalChangelog from "conventional-changelog";
import { createWriteStream } from "fs";

const changelogStream = conventionalChangelog({
  preset: "angular",
  releaseCount: 1
});

changelogStream.pipe(createWriteStream("CHANGELOG.md"));

Capabilities

Input/Output Configuration

Controls where the tool reads existing changelogs and writes output.

# Read changelog from specified file
-i, --infile <file>

# Write changelog to specified file (stdout if unspecified)
-o, --outfile <file>

# Use same file for input and output
-s, --same-file

Usage Examples:

# Read from existing changelog, append new entries
conventional-changelog -i CHANGELOG.md -o CHANGELOG.md

# Same file operation (shorthand)
conventional-changelog -i CHANGELOG.md -s

# Output to different file
conventional-changelog -i OLD_CHANGELOG.md -o NEW_CHANGELOG.md

Preset Configuration

Configures the commit message parsing and output formatting style.

# Specify preset for commit parsing and formatting
-p, --preset <preset>

# Available presets: angular, atom, codemirror, conventionalcommits, 
# ember, eslint, express, jquery, jshint

Usage Examples:

# Use Angular commit convention
conventional-changelog -p angular

# Use conventional commits standard
conventional-changelog -p conventionalcommits

# Use jQuery project style
conventional-changelog -p jquery

Package and Configuration

Specifies package information and custom configuration files.

# Path to package.json file (defaults to closest from cwd)
-k, --pkg <path>

# Path to configuration file
-n, --config <file>

# Path to template context JSON file
-c, --context <file>

Configuration File Format:

// config.js example
module.exports = {
  options: {
    preset: 'angular',
    releaseCount: 1
  },
  gitRawCommitsOpts: {
    from: 'v1.0.0'
  },
  parserOpts: {
    // parser options for commit parsing
  },
  writerOpts: {
    // writer options for changelog formatting
    mainTemplate: '{{commitGroups.[0].commits.[0].type}}{{testContext}}template'
  }
};

Context File Format:

{
  "version": "1.0.0",
  "previousTag": "v0.9.0",
  "currentTag": "v1.0.0",
  "linkCompare": true,
  "repository": "https://github.com/user/repo"
}

Release Control

Controls how many releases to generate and whether to append or prepend.

# Number of releases to generate (0 = regenerate all)
-r, --release-count <count>

# Append newer releases to older ones
-a, --append

# Skip unstable version tags (alpha, beta, rc)
--skip-unstable

# Include unreleased changes in output
-u, --output-unreleased

Usage Examples:

# Generate only the latest release
conventional-changelog -p angular -r 1

# Regenerate entire changelog
conventional-changelog -p angular -r 0

# Append mode (newer releases at end)
conventional-changelog -p angular -a

# Skip pre-release versions
conventional-changelog -p angular --skip-unstable

Scoping and Filtering

Controls which commits and directories are included in the changelog.

# Generate changelog for specific lerna package
-l, --lerna-package <package>

# Tag prefix to consider when reading tags
-t, --tag-prefix <prefix>

# Generate changelog scoped to specific directory
--commit-path <path>

Usage Examples:

# Generate for specific lerna package
conventional-changelog -l my-package@1.0.0

# Use custom tag prefix
conventional-changelog -t v

# Scope to specific directory
conventional-changelog --commit-path packages/my-app

Debug and Logging

Controls verbosity and debugging output.

# Enable verbose output for debugging
-v, --verbose

Usage Examples:

# Enable detailed logging
conventional-changelog -p angular -v

# Debug configuration loading
conventional-changelog -n config.js -v

Integration Patterns

NPM Scripts Integration

{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
    "changelog:all": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
    "version": "conventional-changelog -p angular -i CHANGELOG.md -s && git add CHANGELOG.md"
  }
}

Automated Release Workflow

# Recommended release workflow
# 1. Make changes and commit
# 2. Run version bump
npm version patch

# 3. Update changelog (if using version script)
# This runs automatically via npm version hook

# 4. Commit and tag
git commit -m "chore(release): 1.0.1"
git tag v1.0.1

# 5. Push
git push && git push --tags

Lerna Monorepo Usage

# Generate changelog for specific package
conventional-changelog -l @myorg/package-a@1.0.0 -p angular

# Generate changelog for all packages (run from each package directory)
cd packages/package-a
conventional-changelog -p angular -i CHANGELOG.md -s

Error Handling

The CLI tool exits with specific codes:

  • Exit Code 0: Successful execution
  • Exit Code 1: Error during execution (configuration loading failure, changelog generation error, invalid option combinations)

Common error scenarios:

# Error: infile required with same-file flag
conventional-changelog -s
# Fix: Provide infile
conventional-changelog -i CHANGELOG.md -s

# Error: Invalid config file
conventional-changelog -n invalid-config.js
# Fix: Ensure config file exists and exports valid configuration

# Error: Git repository issues
# Fix: Ensure you're in a git repository with commits

Advanced Configuration

Custom Templates

Configuration files can specify custom templates for changelog formatting:

module.exports = {
  writerOpts: {
    mainTemplate: `# Changelog

{{#each releases}}
## {{title}}
{{#each commits}}
- {{subject}}
{{/each}}
{{/each}}
`,
    commitPartial: '- {{header}}\n'
  }
};

Git Integration Options

module.exports = {
  gitRawCommitsOpts: {
    from: 'v1.0.0',        // Start from specific tag
    to: 'HEAD',            // End at specific ref
    path: './src',         // Limit to path
    format: '%B%n-hash-%n%H%n-gitTags-%n%d%n-committerDate-%n%ci'
  }
};

Parser Customization

module.exports = {
  parserOpts: {
    headerPattern: /^(\w*)(?:\((.*)\))?: (.*)$/,
    headerCorrespondence: ['type', 'scope', 'subject'],
    noteKeywords: ['BREAKING CHANGE', 'BREAKING CHANGES'],
    revertPattern: /^revert:\s([\s\S]*?)\s*This reverts commit (\w*)\./,
    revertCorrespondence: ['header', 'hash']
  }
};

Preset Details

Available Presets

  • angular: Angular project commit convention
  • atom: Atom editor project style
  • codemirror: CodeMirror project style
  • conventionalcommits: Standard conventional commits
  • ember: Ember.js project style
  • eslint: ESLint project style
  • express: Express.js project style
  • jquery: jQuery project style
  • jshint: JSHint project style

Each preset defines specific parsing rules, commit types, and output formatting for different project styles and commit conventions.