Skip to main content

​
Install via NPM

Install git-cliff from NPM for seamless integration with Node.js projects.

​
Quick Start

Run git-cliff without installing: 
npx git-cliff@latest

​
Installation

Install as a dev dependency:
npm install git-cliff --save-dev
Run after installation:
npx git-cliff

​
Detailed Installation Steps

1

Install Node.js

Ensure you have a supported Node.js version:
  • Node.js >= 18.19
  • Node.js >= 20.6
  • Node.js >= 21
Check your version:
node --version
2

Add to project

Install git-cliff in your project:
npm install git-cliff --save-dev
This adds git-cliff to your package.json:
{
  "devDependencies": {
    "git-cliff": "^2.7.0"
  }
}
3

Add npm script

Add a script to your package.json:
{
  "scripts": {
    "changelog": "git-cliff -o CHANGELOG.md",
    "changelog:unreleased": "git-cliff --unreleased",
    "changelog:latest": "git-cliff --latest"
  }
}
4

Run git-cliff

npm run changelog
5

Verify installation

npx git-cliff --version

​
Programmatic API

git-cliff provides a fully typed TypeScript API for integration into your tools.

​
Basic Usage

import { runGitCliff, type Options } from "git-cliff";

const options: Options = {
  output: "CHANGELOG.md",
  latest: true,
};

await runGitCliff(options);

​
Advanced Usage

import { runGitCliff } from "git-cliff";

// Generate full changelog
await runGitCliff({
  output: "CHANGELOG.md",
  tag: "v1.0.0",
});

​
Supported Platforms

NPM packages are distributed for:
PlatformArchitecture
Linuxx64, arm64
macOSx64 (Intel), arm64 (Apple Silicon)
Windowsx64, arm64

​
Integration Examples

Create a release script in scripts/release.js:
import { runGitCliff } from "git-cliff";
import { execSync } from "child_process";

const version = process.argv[2];
if (!version) {
  console.error("Usage: node scripts/release.js <version>");
  process.exit(1);
}

// Generate changelog
await runGitCliff({
  tag: `v${version}`,
  output: "CHANGELOG.md",
});

// Commit and tag
execSync(`git add CHANGELOG.md`);
execSync(`git commit -m "chore: release v${version}"`);
execSync(`git tag v${version}`);

console.log(`Released v${version}`);
Add to package.json:
{
  "scripts": {
    "release": "node scripts/release.js"
  }
}
Usage:
npm run release 1.2.0

​
Troubleshooting

Ensure you’re using a supported Node.js version:
node --version
Minimum versions:
  • = 18.19
  • = 20.6
  • = 21
Update Node.js if needed:
# Using nvm
nvm install 20
nvm use 20
The npm package downloads platform-specific binaries. If the binary fails:
  1. Check your platform is supported
  2. Try reinstalling: 
    rm -rf node_modules package-lock.json
npm install
  3. Clear npm cache: 
    npm cache clean --force
git-cliff includes TypeScript types. Ensure your tsconfig.json includes:
{
  "compilerOptions": {
    "moduleResolution": "node",
    "types": ["node"]
  }
}
Clear npx cache and specify version:
npx clear-npx-cache
npx git-cliff@latest --version

​
Next Steps

Configuration

Configure git-cliff for your project

GitHub Actions

Automate changelog generation

Build docs developers (and LLMs) love

Get started for freeTalk to us