or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

Gulp Conventional Changelog

Gulp Conventional Changelog is a Gulp plugin that wraps the conventional-changelog library to generate changelogs as part of Gulp-based build workflows. It provides a streaming interface that integrates with Gulp's file system and supports both buffer and streaming modes for processing changelog files.

Package Information

Package Name: gulp-conventional-changelog
Package Type: npm
Language: JavaScript (Node.js)
Installation: npm install --save-dev gulp-conventional-changelog

Core Imports

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

For ESM:

import conventionalChangelog from "gulp-conventional-changelog";

Basic Usage

The most common usage pattern for generating changelogs in a Gulp build process:

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

gulp.task("changelog", function () {
  return gulp.src("CHANGELOG.md")
    .pipe(conventionalChangelog({
      preset: "angular"
    }))
    .pipe(gulp.dest("./"));
});

Architecture

The plugin is built around the Node.js Transform stream pattern:

Transform Stream: Operates in object mode, processing Vinyl file objects
Dual Mode Support: Handles both buffer and streaming file contents
Conventional Changelog Integration: Wraps the conventional-changelog library for git commit analysis
Error Handling: Provides proper Gulp plugin error reporting with PluginError
Lazy Loading: Dynamically imports conventional-changelog for better performance

Capabilities

Main Plugin Function

Creates a Gulp transform stream for changelog generation with flexible configuration options.

/**
 * Creates a Gulp transform stream for changelog generation
 * @param opts - Configuration options for conventional-changelog
 * @param context - Context object for changelog generation
 * @param gitRawCommitsOpts - Options for git-raw-commits module
 * @param parserOpts - Options for conventional-commits-parser
 * @param writerOpts - Options for conventional-changelog-writer
 * @returns Transform stream for Gulp pipeline
 */
function conventionalChangelog(
  opts?: ChangelogOptions,
  context?: ChangelogContext,
  gitRawCommitsOpts?: GitRawCommitsOptions,
  parserOpts?: ParserOptions, 
  writerOpts?: WriterOptions
): NodeJS.Transform;

Usage Examples:

// Basic usage with preset
gulp.src("CHANGELOG.md")
  .pipe(conventionalChangelog({
    preset: "angular"
  }))
  .pipe(gulp.dest("./"));

// Full configuration with all options
gulp.src("CHANGELOG.md")
  .pipe(conventionalChangelog({
    preset: "angular",
    releaseCount: 1,
    append: false,
    verbose: true
  }, {
    version: "1.0.0",
    date: new Date().toISOString()
  }, {
    from: "HEAD~10"
  }, {
    noteKeywords: ["BREAKING CHANGE"]
  }, {
    transform: (commit) => commit
  }))
  .pipe(gulp.dest("./"));

// Streaming mode
gulp.src("CHANGELOG.md", { buffer: false })
  .pipe(conventionalChangelog({
    preset: "angular"
  }))
  .pipe(gulp.dest("./"));

// Generate complete changelog (all releases)
gulp.src("CHANGELOG.md", { read: false })
  .pipe(conventionalChangelog({
    preset: "angular",
    releaseCount: 0
  }))
  .pipe(gulp.dest("./"));

// Working with a specific repository directory
gulp.src("CHANGELOG.md")
  .pipe(conventionalChangelog({
    preset: "angular",
    cwd: "/path/to/git/repository"
  }))
  .pipe(gulp.dest("./"));

Types

/**
 * Configuration options for changelog generation
 * @typedef {Object} ChangelogOptions
 * @property {string} [preset] - Conventional changelog preset (e.g., 'angular', 'atom', 'ember')
 * @property {number} [releaseCount] - Number of releases to include (0 = all releases)
 * @property {boolean} [append] - Whether to append new content after existing content (default: false - prepends)
 * @property {boolean} [verbose] - Enable verbose logging (auto-detected from --verbose CLI flag)
 * @property {Function} [debug] - Debug logging function (set to fancyLog when verbose is true)
 * @property {Object} [config] - Configuration object for conventional-changelog
 * @property {Function} [warn] - Warning function for logging issues
 * @property {string} [cwd] - Working directory for git operations (defaults to process.cwd())
 */

/**
 * Context object for changelog generation
 * @typedef {Object} ChangelogContext
 * @property {string} [version] - Version for changelog generation
 * @property {string} [date] - Date for the changelog entry
 * @property {...*} [key] - Additional context properties passed to conventional-changelog
 */

/**
 * Options for git-raw-commits module
 * @typedef {Object} GitRawCommitsOptions
 * @property {string} [from] - Starting point for commit analysis
 * @property {string} [to] - Ending point for commit analysis
 * @property {string} [path] - Path to analyze commits for
 * @property {...*} [key] - Additional git-raw-commits options
 */

/**
 * Options for conventional-commits-parser
 * @typedef {Object} ParserOptions
 * @property {string[]} [noteKeywords] - Keywords that indicate breaking changes
 * @property {...*} [key] - Additional parser configuration
 */

/**
 * Options for conventional-changelog-writer
 * @typedef {Object} WriterOptions
 * @property {Function} [transform] - Transform function for commits
 * @property {...*} [key] - Additional writer configuration
 */

Processing Modes

Buffer Mode (Default)

Input: Vinyl file with Buffer contents
Processing: Changelog content is prepended or appended to existing buffer
Output: Modified Vinyl file with updated Buffer contents

Streaming Mode

Input: Vinyl file with Stream contents
Processing: Uses add-stream to combine changelog output with existing stream
Output: Modified Vinyl file with updated Stream contents

Null Files

Input: Vinyl file with null contents
Processing: File passes through unchanged
Output: Same Vinyl file with null contents

Content Positioning

Prepend Mode (Default)

When append: false or not specified:

New changelog content appears before existing content
Useful for adding latest changes to the top of the changelog

Append Mode

When append: true:

New changelog content appears after existing content
Useful for adding historical changes to the bottom

Full Regeneration

When releaseCount: 0:

Completely replaces file contents with full changelog
File can be read as false since contents will be fully replaced

Error Handling

The plugin provides proper Gulp error handling:

// Errors are wrapped in PluginError with plugin name
class PluginError extends Error {
  plugin: "gulp-conventional-changelog";
  message: string;
}

Common error scenarios:

Invalid git repository or commit history
Malformed conventional commit messages
File system permissions issues
Invalid configuration options

Advanced Configuration

Preset Configuration

// Using built-in presets
conventionalChangelog({ preset: "angular" })
conventionalChangelog({ preset: "atom" })
conventionalChangelog({ preset: "ember" })

// Custom preset configuration
conventionalChangelog({
  preset: {
    name: "custom",
    conventionalChangelog: customConfig
  }
})

Release Targeting

// Latest release only
conventionalChangelog({ releaseCount: 1 })

// Last 3 releases
conventionalChangelog({ releaseCount: 3 })

// All releases (full regeneration)
conventionalChangelog({ releaseCount: 0 })

Git Commit Filtering

conventionalChangelog({
  preset: "angular",
  cwd: "/path/to/repo" // Specify working directory
}, {}, {
  from: "v1.0.0",      // Start from specific tag
  to: "HEAD",          // End at HEAD
  path: "./src"        // Only commits affecting specific path
})