Introduction

@conventional-changelog/git-client is a small wrapper around the git CLI used across the tooling to read a repository’s commits and tags — and to stage, commit, tag, and push during releases. ConventionalGitClient extends it with conventional-commits helpers: parsed commits and semver tags.

Quick start

1. Install @conventional-changelog/git-client:

   pnpm

   pnpm add @conventional-changelog/git-client

   npm

   npm i @conventional-changelog/git-client

   yarn

   yarn add @conventional-changelog/git-client

   Note

   ConventionalGitClient#getCommits also needs conventional-commits-parser and conventional-commits-filter installed.

2. Create a client pointed at a repository:

   import { ConventionalGitClient } from '@conventional-changelog/git-client'
   
   const client = new ConventionalGitClient(process.cwd())

3. Read from the repo — for example, the last semver tag:

   console.log(await client.getLastSemverTag()) // 'v1.2.0'

Reading the history

ConventionalGitClient streams parsed commits (via conventional-commits-parser, with reverts filtered out):

for await (const commit of client.getCommits({ from: 'v1.0.0' })) {
  console.log(commit.type, commit.subject)
}

And it reads semver tags in a few ways:

await client.getLastSemverTag()   // 'v1.2.0' — newest semver tag
await client.getVersionFromTags() // '1.2.0'  — current version (cleaned), or null

for await (const tag of client.getSemverTags()) {
  console.log(tag) // 'v1.2.0', 'v1.1.0', …
}

The base GitClient exposes the raw plumbing too — getRawCommits(), getTags(), getLastTag(), getConfig(), getCurrentBranch().

Staging and releasing

GitClient (which ConventionalGitClient extends) wraps the write operations used by release tooling:

import { GitClient } from '@conventional-changelog/git-client'

const client = new GitClient(process.cwd())

await client.add('CHANGELOG.md')
await client.commit({ message: 'chore: release v1.2.0' })
await client.tag({ name: 'v1.2.0' })
await client.push('master')

Two clients

Use GitClient for plain git operations, or ConventionalGitClient when you also need parsed commits and semver tags — it inherits every GitClient method.

See the JS API for the full list of methods and their parameters.