or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

changelog-generation.mdconfiguration.mdgit-operations.mdgithub-integration.mdindex.mdrepository-analysis.mdversion-management.md
tile.json

index.mddocs/

Changelogen

Changelogen is a comprehensive changelog generation tool that automatically creates beautiful, readable changelogs from conventional commits in git repositories. It provides both CLI and programmatic interfaces for generating semantic version-aware changelogs, supports automatic version bumping in package.json, and includes integrated release management with git tagging and commit creation.

Package Information

  • Package Name: changelogen
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install changelogen

Core Imports

import {
  // Core git operations
  getGitDiff,
  parseCommits,
  getCurrentGitRef,
  
  // Changelog generation
  generateMarkDown,
  parseChangelogMarkdown,
  
  // Configuration
  loadChangelogConfig,
  
  // Version management
  bumpVersion,
  determineSemverChange,
  
  // GitHub integration
  syncGithubRelease,
  createGithubRelease,
  
  // Repository utilities
  getRepoConfig,
  formatReference
} from "changelogen";

For CommonJS:

const {
  getGitDiff,
  parseCommits,
  generateMarkDown,
  loadChangelogConfig,
  bumpVersion
} = require("changelogen");

Basic Usage

import {
  loadChangelogConfig,
  getGitDiff,
  parseCommits,
  generateMarkDown
} from "changelogen";

// Load configuration
const config = await loadChangelogConfig(process.cwd(), {
  from: "v1.0.0",
  to: "HEAD",
  output: "CHANGELOG.md"
});

// Get commits between references
const rawCommits = await getGitDiff(config.from, config.to, config.cwd);

// Parse commits as conventional commits
const commits = parseCommits(rawCommits, config);

// Generate markdown changelog
const markdown = await generateMarkDown(commits, config);

console.log(markdown);

Architecture

Changelogen is built around several key components:

  • Git Integration: Direct git command execution and commit parsing for extracting conventional commit information
  • Configuration System: Flexible configuration loading from multiple sources (files, package.json, CLI args)
  • Markdown Engine: Template-based changelog generation with customizable formatting and emoji support
  • Version Management: Semantic versioning analysis and automated package.json version bumping
  • GitHub Integration: Full GitHub API integration for release creation and synchronization
  • Multi-provider Support: Repository provider abstraction supporting GitHub, GitLab, and Bitbucket

CLI Usage

Changelogen provides a command-line interface:

# Generate changelog and display in console
npx changelogen

# Generate changelog with version bump
npx changelogen --bump

# Full release workflow (bump, changelog, commit, tag)
npx changelogen --release

# Sync with GitHub releases
npx changelogen gh release

Capabilities

Core Git Operations

Essential git operations for retrieving commit history, parsing conventional commits, and extracting repository information.

function getGitDiff(
  from: string | undefined,
  to?: string = "HEAD",
  cwd?: string
): Promise<RawGitCommit[]>;

function parseCommits(
  commits: RawGitCommit[],
  config: ChangelogConfig
): GitCommit[];

Git Operations

Changelog Generation

Core markdown generation functionality for creating formatted changelogs from parsed commits with customizable templates and formatting.

function generateMarkDown(
  commits: GitCommit[],
  config: ResolvedChangelogConfig
): Promise<string>;

function parseChangelogMarkdown(
  contents: string
): { releases: { version?: string; body: string }[] };

Changelog Generation

Version Management

Semantic version analysis and automated package.json version bumping based on conventional commit types.

function determineSemverChange(
  commits: GitCommit[],
  config: ChangelogConfig
): SemverBumpType | null;

function bumpVersion(
  commits: GitCommit[],
  config: ChangelogConfig,
  opts?: BumpVersionOptions
): Promise<string | false>;

type SemverBumpType =
  | "major"
  | "premajor" 
  | "minor"
  | "preminor"
  | "patch"
  | "prepatch"
  | "prerelease";

Version Management

GitHub Integration

Full GitHub API integration for creating, updating, and synchronizing releases with changelog content.

function syncGithubRelease(
  config: ResolvedChangelogConfig,
  release: { version: string; body: string }
): Promise<{
  status: "created" | "updated" | "manual";
  id?: string;
  url?: string;
  error?: any;
}>;

function createGithubRelease(
  config: ResolvedChangelogConfig,
  body: GithubRelease
): Promise<GithubRelease>;

GitHub Integration

Configuration Management

Flexible configuration system supporting multiple configuration sources and automatic resolution of git repository information.

function loadChangelogConfig(
  cwd: string,
  overrides?: Partial<ChangelogConfig>
): Promise<ResolvedChangelogConfig>;

interface ChangelogConfig {
  cwd: string;
  types: Record<string, { title: string; semver?: SemverBumpType } | boolean>;
  scopeMap: Record<string, string>;
  repo?: RepoConfig | string;
  tokens: Partial<Record<RepoProvider, string>>;
  from: string;
  to: string;
  newVersion?: string;
  signTags?: boolean;
  output: string | boolean;
  publish: {
    args?: string[];
    tag?: string;
    private?: boolean;
  };
  templates: {
    commitMessage?: string;
    tagMessage?: string;
    tagBody?: string;
  };
  noAuthors: boolean;
  excludeAuthors: string[];
  hideAuthorEmail?: boolean;
}

Configuration Management

Repository Analysis

Repository provider detection and URL parsing with support for GitHub, GitLab, Bitbucket, and self-hosted instances.

function getRepoConfig(repoUrl?: string): RepoConfig;

function formatReference(ref: Reference, repo?: RepoConfig): string;

type RepoProvider = "github" | "gitlab" | "bitbucket";

interface RepoConfig {
  domain?: string;
  repo?: string;
  provider?: RepoProvider;
  token?: string;
}

Repository Analysis

Types

interface GitCommitAuthor {
  name: string;
  email: string;
}

interface RawGitCommit {
  message: string;
  body: string;
  shortHash: string;
  author: GitCommitAuthor;
}

interface GitCommit extends RawGitCommit {
  description: string;
  type: string;
  scope: string;
  references: Reference[];
  authors: GitCommitAuthor[];
  isBreaking: boolean;
}

interface Reference {
  type: "hash" | "issue" | "pull-request";
  value: string;
}

interface GithubRelease {
  id?: string;
  tag_name: string;
  name?: string;
  body?: string;
  draft?: boolean;
  prerelease?: boolean;
}

interface BumpVersionOptions {
  type?: SemverBumpType;
  preid?: string;
  suffix?: boolean;
}

type ResolvedChangelogConfig = Omit<ChangelogConfig, "repo"> & {
  repo: RepoConfig;
};