Skip to content
Conventional Changelog

Introduction

conventional-commits-filter removes reverted commits from a list of parsed commits. A revert commit and the commit it reverts cancel each other out, so neither ends up in the changelog. It’s the middle stage of the pipeline — parser → filter → writer — and conventional-changelog applies it automatically.

Quick start

Section titled “Quick start”

  1. Install conventional-commits-filter:

    pnpm add conventional-commits-filter

  2. Filter a list of parsed commits — here a revert and the feat it reverts, plus an unrelated fix:

    import { filterRevertedCommitsSync } from 'conventional-commits-filter'
    

    const commits = [
      {
        type: 'revert',
        header: 'revert: feat(api): add caching',
        revert: { header: 'feat(api): add caching', hash: '9c1e2b3' },
        hash: 'a1b2c3d',
        notes: [],
        references: []
      },
      {
        type: 'feat',
        scope: 'api',
        subject: 'add caching',
        header: 'feat(api): add caching',
        revert: null,
        hash: '9c1e2b3',
        notes: [],
        references: []
      },
      {
        type: 'fix',
        scope: 'cli',
        subject: 'handle missing config',
        header: 'fix(cli): handle missing config',
        revert: null,
        hash: 'e5f6a7b',
        notes: [],
        references: []
      }
    ]
    

    const kept = Array.from(filterRevertedCommitsSync(commits))

  3. Get the surviving commits — the revert and the feat it reverts are gone, so only the fix remains:

    [
      {
        type: 'fix',
        scope: 'cli',
        subject: 'handle missing config',
        header: 'fix(cli): handle missing config',
        revert: null,
        hash: 'e5f6a7b',
        notes: [],
        references: []
      }
    ]

Streaming

Section titled “Streaming”

filterRevertedCommits is an async-generator function for stream.pipeline, and filterRevertedCommitsStream returns a Node.js Transform:

import { filterRevertedCommits, filterRevertedCommitsStream } from 'conventional-commits-filter'
import { pipeline } from 'node:stream/promises'
import { Readable } from 'node:stream'


// Async iterable
await pipeline(
  commits,
  filterRevertedCommits,
  async function* (filtered) {
    for await (const commit of filtered) {
      console.log(commit)
    }
  }
)


// Node.js stream
Readable.from(commits)
  .pipe(filterRevertedCommitsStream())
  .on('data', commit => console.log(commit))

How reverts are matched

Section titled “How reverts are matched”

A commit is recognized as a revert when it has a revert field — set by conventional-commits-parser from its revertPattern. A held revert cancels a later commit when the revert’s revert object matches that commit’s fields (its header and hash).