### Full configuration example for changelogithub

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

A comprehensive example of `defineConfig` showing all available options for git references, repository settings, GitHub integration, release metadata, output formatting, and customization.

```typescript
export default defineConfig({
  // Git references
  from: 'v1.0.0',
  to: 'v2.0.0',
  
  // Repository
  repo: 'owner/repo',
  releaseRepo: 'owner/releases', // For monorepos
  
  // GitHub
  token: process.env.GITHUB_TOKEN,
  baseUrl: 'github.com',
  baseUrlApi: 'api.github.com',
  
  // Release metadata
  name: 'Version 2.0',
  draft: false,
  prerelease: false,
  
  // Output formatting
  style: 'markdown', // or 'plain'
  emoji: true,
  capitalize: true,
  contributors: true,
  group: true,
  
  // Customization
  tag: 'v%s',
  assets: ['dist/*.js', 'dist/*.css'],
  titles: {
    breakingChanges: '🚨 Breaking Changes'
  },
  scopeMap: {
    'api': 'API',
    'ui': 'User Interface'
  },
  types: {
    feat: { title: '🚀 Features' },
    fix: { title: '🐞 Bug Fixes' },
    perf: { title: '🏎 Performance' }
  }
})
```

--------------------------------

### Install changelogithub

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Install the package using npm or use it directly with npx.

```bash
npm install changelogithub
# or use directly
npx changelogithub
```

--------------------------------

### Example Changelogithub Configuration

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/README.md

An example configuration file for changelogithub using TypeScript. This demonstrates how to set options like contributors, emoji usage, grouping, and scope mapping.

```typescript
import { defineConfig } from 'changelogithub'

export default defineConfig({
  contributors: true,
  emoji: true,
  group: true,
  scopeMap: {
    'api': 'API',
    'ui': 'User Interface'
  }
})
```

--------------------------------

### Install changelogithub

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/cli.md

Install the changelogithub CLI globally using npm or use it directly with npx.

```bash
npm install -g changelogithub
# or use directly
npx changelogithub
```

--------------------------------

### Example Configuration in package.json

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/configuration.md

Shows how to configure changelog generation directly within the package.json file. This is a convenient way to set basic options for the project.

```json
{
  "changelogithub": {
    "contributors": true,
    "emoji": true,
    "group": true,
    "style": "markdown"
  }
}
```

--------------------------------

### Example Conventional Commits

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/README.md

Provides examples of valid conventional commit messages. These demonstrate different types, scopes, and breaking change indicators.

```text
feat(api): add new endpoint
fix(ui): correct button alignment
docs: update README
perf!: remove deprecated API
feat!: redesign architecture
```

--------------------------------

### Monorepo Setup

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/cli.md

Configure the CLI to use one GitHub repository for generating the changelog while tagging releases in another repository, suitable for monorepos.

```bash
changelogithub --github owner/main-repo --release-github owner/releases-repo
```

--------------------------------

### Example Configuration File (changelogithub.config.ts)

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/configuration.md

Demonstrates how to configure changelog generation using a TypeScript configuration file. This file allows for detailed customization of release titles, scope mapping, and commit type definitions.

```typescript
import { defineConfig } from 'changelogithub'

export default defineConfig({
  contributors: true,
  capitalize: true,
  emoji: true,
  group: true,
  tag: 'v%s',
  style: 'markdown',
  titles: {
    breakingChanges: '🚨 Breaking Changes'
  },
  scopeMap: {
    'core': 'Core',
    'api': 'API',
    'ui': 'User Interface'
  }
})
```

--------------------------------

### Example Type Configuration

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/configuration.md

Shows how to define custom commit types for grouping conventional commits in the changelog. Only types defined here will be included in the output.

```typescript
types: {
  feat: { title: '🚀 Features' },
  fix: { title: '🐞 Bug Fixes' },
  perf: { title: '🏎 Performance' },
  docs: { title: '📚 Documentation' }
}
```

--------------------------------

### Example Scope Mapping

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/configuration.md

Demonstrates how to use the `scopeMap` option to rename scope names in the changelog. This allows for more user-friendly display names for different parts of the project.

```typescript
scopeMap: {
  'auth': 'Authentication',
  'db': 'Database',
  'api': 'API'
}
```

--------------------------------

### Handle Cannot Parse GitHub Repo Error

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/errors.md

This example shows how an invalid remote origin URL that does not match the expected GitHub format will cause an error when trying to get the GitHub repository information.

```bash
# If repository isn't a GitHub repo
git remote -v  # Shows: origin  https://example.com/repo.git
await getGitHubRepo('github.com')  # Throws error
```

--------------------------------

### Get All Git Tags

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/README.md

Retrieves a list of all tags present in the git repository.

```typescript
getGitTags(): Promise<string[]>
```

--------------------------------

### Get Release by Tag

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/endpoints.md

Checks if a release already exists for a given tag. Requires authentication and specific headers.

```APIDOC
## GET /repos/{owner}/{repo}/releases/tags/{tag}

### Description
Check if a release already exists for the current tag.

### Method
GET

### Endpoint
`/repos/{owner}/{repo}/releases/tags/{tag}`

### Request Example
```http
GET https://api.github.com/repos/antfu/changelogithub/releases/tags/v2.0.0
Authorization: token ghp_xxxx
Accept: application/vnd.github.v3+json
```

### Response
#### Success Response (200 OK)
- **id** (integer) - The release ID.
- **url** (string) - The API URL for the release.
- **html_url** (string) - The URL to the release on GitHub.
- **upload_url** (string) - The URL for uploading assets.
- **tag_name** (string) - The name of the tag.
- **name** (string) - The display name of the release.
- **body** (string) - The release notes.
- **draft** (boolean) - Whether the release is a draft.
- **prerelease** (boolean) - Whether the release is a prerelease.
- **created_at** (string) - The timestamp when the release was created.
- **published_at** (string) - The timestamp when the release was published.

#### Response Example
```json
{
  "id": 123456,
  "url": "https://api.github.com/repos/antfu/changelogithub/releases/123456",
  "html_url": "https://github.com/antfu/changelogithub/releases/tag/v2.0.0",
  "upload_url": "https://uploads.github.com/repos/antfu/changelogithub/releases/123456/assets{?name,label}",
  "tag_name": "v2.0.0",
  "name": "v2.0.0",
  "body": "...",
  "draft": false,
  "prerelease": false,
  "created_at": "2024-01-01T00:00:00Z",
  "published_at": "2024-01-01T00:00:00Z"
}
```

#### Response Example (404 Not Found)
Release doesn't exist yet.
```

--------------------------------

### GET Release by Tag

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/endpoints.md

Checks if a release already exists for a given tag. Requires a GitHub token in the Authorization header.

```http
GET https://api.github.com/repos/antfu/changelogithub/releases/tags/v2.0.0
Authorization: token ghp_xxxx
Accept: application/vnd.github.v3+json
```

--------------------------------

### Get GitHub Repository from Git Config

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/README.md

Retrieves the GitHub repository information from the local git configuration.

```typescript
getGitHubRepo(baseUrl: string): Promise<string>
```

--------------------------------

### Custom Formatting Options

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Control the output style and content using flags like `--style`, `--emoji`, and `--group`. For example, use `--style plain` for email-friendly text.

```bash
# Plain text for emails
changelogithub --style plain

# Without emoji
changelogithub --emoji false

# Group all scopes
changelogithub --group true
```

--------------------------------

### GitHub Actions Workflow for Release

Source: https://github.com/antfu/changelogithub/blob/main/README.md

Integrate changelogithub into your GitHub Actions to automatically generate release notes when a new tag is pushed. Ensure you have the necessary permissions and node setup.

```yaml
# .github/workflows/release.yml

name: Release

permissions:
  contents: write

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Set node
        uses: actions/setup-node@v6
        with:
          registry-url: https://registry.npmjs.org/
          node-version: lts/*

      - run: npx changelogithub # or changelogithub@0.12 to ensure a stable result
        env:
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
```

--------------------------------

### Handle GitHub API Authentication Errors

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/errors.md

This example demonstrates how an invalid or expired GitHub token will lead to a 401 Unauthorized error when interacting with the GitHub API.

```bash
GITHUB_TOKEN=invalid_token npx changelogithub
# Throws: 401 Unauthorized from GitHub API
```

--------------------------------

### Basic Usage

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/cli.md

Generate a changelog for the current repository. Ensure the GITHUB_TOKEN environment variable is set.

```bash
changelogithub
```

--------------------------------

### Normalize Tag Template

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/INDEX.md

Get a normalized tag template string using getSafeTagTemplate.

```typescript
import { getSafeTagTemplate } from 'changelogithub/git'

const tagTemplate = await getSafeTagTemplate()
console.log(tagTemplate)
```

--------------------------------

### Changelogithub CLI essential options

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Lists essential command-line options for changelogithub, including token, dry run, output path, and style.

```bash
--token <path>        # GitHub token (or GITHUB_TOKEN env)
--dry                 # Preview only
--output <path>       # Save to file
--style <style>       # markdown or plain
```

--------------------------------

### Get GitHub Repository Information

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/INDEX.md

Extract repository information from Git using getGitHubRepo.

```typescript
import { getGitHubRepo } from 'changelogithub/git'

const repo = await getGitHubRepo()
console.log(repo)
```

--------------------------------

### Resolve GitHub Author Info

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/INDEX.md

Get GitHub login information for an author using resolveAuthorInfo.

```typescript
import { resolveAuthorInfo } from 'changelogithub/github'

const authorInfo = await resolveAuthorInfo('John Doe')
console.log(authorInfo)
```

--------------------------------

### Changelogithub CLI Usage

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/README.md

Demonstrates common command-line interface commands for changelogithub. Use these to generate, preview, or format changelogs.

```bash
changelogithub [options]
```

```bash
# Generate and release
changelogithub
```

```bash
# Preview without releasing
changelogithub --dry
```

```bash
# Save to file
changelogithub --output CHANGELOG.md
```

```bash
# Plain text format
changelogithub --style plain
```

```bash
# Upload assets
changelogithub --assets 'dist/*.js'
```

--------------------------------

### Get First Git Commit

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/INDEX.md

Retrieve the first commit in the Git history using getFirstGitCommit.

```typescript
import { getFirstGitCommit } from 'changelogithub/git'

const firstCommit = await getFirstGitCommit()
console.log(firstCommit)
```

--------------------------------

### Get Current Git Branch

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/README.md

Retrieves the name of the current active branch in the git repository.

```typescript
getCurrentGitBranch(): Promise<string>
```

--------------------------------

### Minimal configuration for changelogithub

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Configure changelogithub with minimal settings using `defineConfig`. Repository details are auto-detected from git if not specified.

```typescript
import { defineConfig } from 'changelogithub'

export default defineConfig({
  // Auto-detected from git if not specified
})
```

--------------------------------

### Get Current Git Branch

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/INDEX.md

Retrieve the current Git branch or tag using getCurrentGitBranch.

```typescript
import { getCurrentGitBranch } from 'changelogithub/git'

const branch = await getCurrentGitBranch()
console.log(branch)
```

--------------------------------

### Changelogithub CLI release options

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Command-line options for configuring release details, including custom name, draft status, prerelease status, and contributor inclusion.

```bash
--name <name>         # Custom release name
--draft               # Create as draft
--prerelease          # Mark as prerelease
--contributors        # Include contributors (default)
```

--------------------------------

### generate() with Custom Configuration

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/api-reference/generate.md

Shows how to use the generate function with custom configuration options, including specifying commit ranges, repository, and output style.

```typescript
import { generate } from 'changelogithub'

const result = await generate({
  from: 'v1.0.0',
  to: 'v2.0.0',
  repo: 'antfu/changelogithub',
  token: process.env.GITHUB_TOKEN,
  contributors: true,
  emoji: true,
  style: 'markdown'
})

console.log(`Generated ${result.commits.length} commits`)
console.log(result.output)
```

--------------------------------

### Get Last Matching Git Tag

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/README.md

Finds the most recent git tag that matches a given filter and template.

```typescript
getLastMatchingTag(inputTag: string, tagFilter: (tag: string) => boolean, tagTemplate: string): Promise<string | undefined>
```

--------------------------------

### Get Commit

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/endpoints.md

Fetches author information for a specific commit using its reference. Requires authentication and specific headers.

```APIDOC
## GET /repos/{owner}/{repo}/commits/{ref}

### Description
Fetch author information for a specific commit.

### Method
GET

### Endpoint
`/repos/{owner}/{repo}/commits/{ref}`

### Request Example
```http
GET https://api.github.com/repos/antfu/changelogithub/commits/abc123def456
Authorization: token ghp_xxxx
Accept: application/vnd.github.v3+json
```

### Response
#### Success Response (200 OK)
- **sha** (string) - The commit SHA.
- **url** (string) - The API URL for the commit.
- **html_url** (string) - The URL to the commit on GitHub.
- **author** (object) - Information about the commit author (GitHub user).
  - **login** (string) - The author's GitHub login.
  - **id** (integer) - The author's GitHub user ID.
  - **type** (string) - The type of the author account.
- **commit** (object) - Commit details.
  - **message** (string) - The commit message.
  - **author** (object) - Author details from the commit.
    - **name** (string) - The author's name.
    - **email** (string) - The author's email.

#### Response Example
```json
{
  "sha": "abc123def456...",
  "url": "https://api.github.com/repos/antfu/changelogithub/commits/abc123def456",
  "html_url": "https://github.com/antfu/changelogithub/commit/abc123def456",
  "author": {
    "login": "johndoe",
    "id": 123456,
    "type": "User"
  },
  "commit": {
    "message": "feat: add new feature",
    "author": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}
```
```

--------------------------------

### Preview Changelog Locally

Source: https://github.com/antfu/changelogithub/blob/main/README.md

Use this command to preview the generated changelog locally without actually creating or updating release notes. This is useful for testing your configuration.

```bash
npx changelogithub --dry
```

--------------------------------

### GitHub Actions workflow for release

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

A sample GitHub Actions workflow that checks out code, sets up Node.js, runs changelogithub to generate a changelog, and uploads assets to the release.

```yaml
name: Release
permissions:
  contents: write
on:
  push:
    tags:
      - 'v*'
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0  # Important: get full history
      
      - uses: actions/setup-node@v6
        with:
          node-version: lts/*
      
      - run: npx changelogithub
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      
      - if: always()
        name: Upload assets
        run: npx changelogithub --assets 'dist/*'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Prerelease

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/cli.md

Mark the generated release as a prerelease on GitHub.

```bash
changelogithub --prerelease
```

--------------------------------

### GET Commit Information

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/endpoints.md

Fetches author information for a specific commit using its SHA. Requires a GitHub token.

```http
GET https://api.github.com/repos/antfu/changelogithub/commits/abc123def456
Authorization: token ghp_xxxx
Accept: application/vnd.github.v3+json
```

--------------------------------

### Changelogithub CLI repository options

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Command-line options for specifying the GitHub repository and git references, such as owner/repo, release repo, and start/end tags.

```bash
--github <repo>       # owner/repo
--release-github      # Override release repo
--from <ref>          # Start tag (auto-detected)
--to <ref>            # End tag (auto-detected)
```

--------------------------------

### Capitalize String

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/api-reference/utils.md

Capitalizes the first letter of a string. Handles empty strings and strings starting with non-alphabetic characters.

```typescript
function capitalize(str: string): string
capitalize('hello')      // 'Hello'
capitalize('HELLO')      // 'HELLO'
capitalize('')           // ''
capitalize('123abc')     // '123abc'
```

--------------------------------

### Basic Usage of generate()

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/api-reference/generate.md

Demonstrates the basic usage of the generate function to create a changelog. It requires a GitHub token for fetching commit data.

```typescript
import { generate } from 'changelogithub'

const result = await generate({
  token: process.env.GITHUB_TOKEN
})

console.log(result.output)
```

--------------------------------

### Use changelogithub as a library

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Import and use the `generate` and `sendRelease` functions to programmatically create changelogs and releases.

```typescript
import { generate, sendRelease } from 'changelogithub'

const { output, config } = await generate({
  token: process.env.GITHUB_TOKEN
})

console.log(output)

// Optional: Create release on GitHub
await sendRelease(config, output)
```

--------------------------------

### Get First Git Commit

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/api-reference/git.md

Retrieves the hash of the first (oldest) commit in the repository. Executes `git rev-list --max-parents=0 HEAD`.

```typescript
import { getFirstGitCommit } from 'changelogithub'

const first = await getFirstGitCommit()
console.log(first)  // "a1b2c3d4e5f6..."
```

--------------------------------

### Preview Changelog in CI (Dry Run)

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Run `changelogithub --dry` to preview the changelog content without publishing. This is useful for verifying output in CI environments.

```bash
# Preview changelog before publishing
changelogithub --dry

# Output shows what would be released
```

--------------------------------

### Dry Run

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/cli.md

Preview the generated changelog without actually creating a release on GitHub.

```bash
changelogithub --dry
```

--------------------------------

### Draft Release

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/cli.md

Create a draft release on GitHub, allowing for review before publishing.

```bash
changelogithub --draft
```

--------------------------------

### Dry Run with generate()

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/api-reference/generate.md

Illustrates how to perform a dry run with the generate function to preview the changelog output without making actual API calls. Requires a GitHub token.

```typescript
import { generate } from 'changelogithub'

const result = await generate({
  dry: true,
  token: process.env.GITHUB_TOKEN
})

// Preview output without making API calls
console.log(result.output)
```

--------------------------------

### Get Current Git Branch or Tag

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/api-reference/git.md

Retrieves the name of the current git branch or tag. This is useful for identifying the current version or branch context.

```typescript
import { getCurrentGitBranch } from 'changelogithub'

const current = await getCurrentGitBranch()
console.log(current)  // "main" or "v1.2.3"
```

--------------------------------

### Output to File

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/cli.md

Save the generated changelog to a local file instead of publishing it to GitHub.

```bash
changelogithub --output CHANGELOG.md
```

--------------------------------

### Default Configuration Object

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/configuration.md

Illustrates the default configuration settings used by changelogithub. These defaults are applied if no specific configuration is provided.

```typescript
{
  scopeMap: {},
  types: {
    feat: { title: '🚀 Features' },
    fix: { title: '🐞 Bug Fixes' },
    perf: { title: '🏎 Performance' }
  },
  titles: {
    breakingChanges: '🚨 Breaking Changes'
  },
  contributors: true,
  emoji: true,
  capitalize: true,
  group: true,
  tag: 'v%s',
  style: 'markdown'
}
```

--------------------------------

### Get Git Reference for Tag

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/endpoints.md

Verifies if a specific tag exists on GitHub for a given repository. This is useful for checking the existence of release tags before performing operations.

```APIDOC
## GET /repos/{owner}/{repo}/git/refs/tags/{tag}

### Description
Verify that a tag exists on GitHub.

### Method
GET

### Endpoint
`/repos/{owner}/{repo}/git/refs/tags/{tag}`

### Parameters
#### Path Parameters
- **owner** (string) - Required - The owner of the repository.
- **repo** (string) - Required - The name of the repository.
- **tag** (string) - Required - The name of the tag.

### Request Example
```http
GET https://api.github.com/repos/antfu/changelogithub/git/refs/tags/v2.0.0
Authorization: token ghp_xxxx
Accept: application/vnd.github.v3+json
```

### Response
#### Success Response (200 OK)
- **ref** (string) - The full reference name of the tag.
- **url** (string) - The API URL for the tag reference.
- **object** (object) - Information about the Git object the ref points to.
  - **sha** (string) - The SHA of the Git object.
  - **type** (string) - The type of the Git object (e.g., 'commit').
  - **url** (string) - The API URL for the Git object.

#### Response Example
```json
{
  "ref": "refs/tags/v2.0.0",
  "url": "https://api.github.com/repos/antfu/changelogithub/git/refs/tags/v2.0.0",
  "object": {
    "sha": "abc123def456...",
    "type": "commit",
    "url": "https://api.github.com/repos/antfu/changelogithub/git/commits/abc123def456"
  }
}
```

#### Error Response (404 Not Found)
Tag doesn't exist.
```

--------------------------------

### Main Functions

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/README.md

Core functions for generating changelogs and managing configuration.

```APIDOC
## generate()

### Description
Generates GitHub release notes from conventional commits.

### Method
`generate(options: ChangelogOptions): Promise<{ config: ResolvedChangelogOptions, output: string, commits: Commit[] }>`

### Parameters
- **options** (ChangelogOptions) - Options for changelog generation.
```

```APIDOC
## defineConfig()

### Description
Defines configuration, primarily for TypeScript support.

### Method
`defineConfig(config: ChangelogOptions): ChangelogOptions`

### Parameters
- **config** (ChangelogOptions) - The configuration object.
```

```APIDOC
## resolveConfig()

### Description
Resolves configuration, applying defaults.

### Method
`resolveConfig(options: ChangelogOptions): Promise<ResolvedChangelogOptions>`

### Parameters
- **options** (ChangelogOptions) - The configuration options to resolve.
```

--------------------------------

### Plain Text Output

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/cli.md

Generate the changelog in plain text format instead of the default Markdown.

```bash
changelogithub --style plain
```

--------------------------------

### Typical GitHub Actions Workflow for Release

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/cli.md

This YAML workflow automates the release process using changelogithub. It checks out code, sets up Node.js, and runs the changelogithub CLI, requiring a GITHUB_TOKEN with 'contents:write' and 'repo' permissions.

```yaml
name: Release
permissions:
  contents: write
on:
  push:
    tags:
      - 'v*'
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v6
        with:
          node-version: lts/*
      - run: npx changelogithub
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Configure Checkout Action for Full History

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/errors.md

In CI environments, shallow clones can cause issues. Configure the actions/checkout action with `fetch-depth: 0` to ensure the full git history is fetched.

```yaml
- uses: actions/checkout@v6
  with:
    fetch-depth: 0  # Full history
```

--------------------------------

### File Organization Overview

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/MANIFEST.md

Provides a visual representation of the project's directory structure and the purpose of key documentation files.

```tree
output/
├── INDEX.md                    ← Start here
├── README.md                   ← Project overview
├── quick-reference.md          ← Quick lookup
├── types.md                    ← Type definitions
├── configuration.md            ← Config options
├── cli.md                      ← CLI usage
├── endpoints.md                ← GitHub API endpoints
├── errors.md                   ← Error handling
├── MANIFEST.md                 ← This file
├── api-reference/
│   ├── generate.md            ← generate()
│   ├── config.md              ← defineConfig(), resolveConfig()
│   ├── git.md                 ← Git operations
│   ├── github.md              ← GitHub API
│   ├── parse.md               ← Commit parsing
│   ├── markdown.md            ← Markdown output
│   ├── plain.md               ← Plain text output
│   └── utils.md               ← Utility functions

```

--------------------------------

### POST Create Release

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/endpoints.md

Creates a new GitHub release with specified tag, name, body, and draft/prerelease status. Requires a GitHub token.

```http
POST https://api.github.com/repos/antfu/changelogithub/releases
Authorization: token ghp_xxxx
Accept: application/vnd.github.v3+json
Content-Type: application/json

{
  "tag_name": "v2.0.0",
  "name": "Version 2.0",
  "body": "## Features\n\n- New feature description",
  "draft": false,
  "prerelease": false
}
```

--------------------------------

### Troubleshooting: No Commits Found

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

If no commits are found, ensure a full Git clone is used (`git fetch --unshallow`) or specify the commit range using `--from` and `--to`.

```bash
# Use full clone (not shallow)
git fetch --unshallow

# Or check config
changelogithub --from v1.0.0 --to v2.0.0 --dry
```

--------------------------------

### Changelogithub CLI asset options

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Command-line option for specifying files to upload as assets to the GitHub release. Supports glob patterns.

```bash
--assets <paths...>   # Files to upload (glob patterns supported)
```

--------------------------------

### Generate changelog via CLI

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Generate a changelog using the CLI. Requires GITHUB_TOKEN environment variable. Options include dry run, output file, style, and assets.

```bash
# Generate changelog (requires GITHUB_TOKEN environment variable)
changelogithub

# Preview without releasing
changelogithub --dry

# Save to file
changelogithub --output CHANGELOG.md

# Plain text format
changelogithub --style plain

# Upload files to release
changelogithub --assets dist/*.js
```

--------------------------------

### CI/CD Pipelines - Programmatic Usage

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/README.md

Programmatically generate and send release notes within build scripts using the changelogithub library. Requires a GitHub token for authentication.

```typescript
import { generate, sendRelease } from 'changelogithub'

const { output, config } = await generate({ token: process.env.GITHUB_TOKEN })
await sendRelease(config, output)
```

--------------------------------

### Define Configuration

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/INDEX.md

Use defineConfig to create type-checked configuration objects for changelogithub.

```typescript
import { defineConfig } from 'changelogithub'

export default defineConfig({
  // ... your configuration
})
```

--------------------------------

### Saving Generated Changelog to File

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/api-reference/generate.md

Demonstrates how to generate a changelog in Markdown format and save it to a file named CHANGELOG.md using Node.js file system promises.

```typescript
import { generate } from 'changelogithub'
import fs from 'node:fs/promises'

const result = await generate({
  style: 'markdown'
})

await fs.writeFile('CHANGELOG.md', result.output, 'utf-8')
```

--------------------------------

### generate()

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/api-reference/generate.md

Main entry point for generating a changelog from git commits. It resolves configuration, fetches and parses commits, resolves author information, and generates the changelog output.

```APIDOC
## generate(options: ChangelogOptions)

### Description
Main entry point for generating a changelog from git commits. This function orchestrates the complete changelog generation process, including configuration resolution, commit fetching and parsing, author information resolution, and output generation.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (ChangelogOptions) - Required - Configuration options for changelog generation.

### Request Example
```typescript
import { generate } from 'changelogithub'

const result = await generate({
  token: process.env.GITHUB_TOKEN
})

console.log(result.output)
```

### Response
#### Success Response (200)
- **config** (ResolvedChangelogOptions) - Fully resolved configuration after applying defaults and auto-detection.
- **output** (string) - Generated changelog content as string (HTML/Markdown or plain text depending on style).
- **commits** (Commit[]) - Array of parsed commits included in the changelog.

#### Response Example
```json
{
  "config": { ... },
  "output": "# Changelog\n...",
  "commits": [
    { ... },
    { ... }
  ]
}
```

### Throws
- **Error** if configuration is invalid (e.g., invalid repository format).
- **Error** if git commands fail.
- **Error** if GitHub API requests fail (when fetching author info).
```

--------------------------------

### Run Changelogithub in Dry Run Mode

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/errors.md

Execute changelogithub in dry run mode to preview the changelog generation without making any actual API calls or changes to your repository.

```bash
# Preview without making API calls
changelogithub --dry
```

--------------------------------

### Changelogithub CLI formatting options

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Command-line options to control changelog formatting, such as capitalizing messages, using emojis, and grouping by scope.

```bash
--capitalize          # Capitalize messages (default)
--emoji               # Use emoji (default)
--group               # Group by scope (default)
```

--------------------------------

### Upload Assets to Release

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Attach files to a GitHub release using the `--assets` flag. Supports single files, multiple files, and glob patterns.

```bash
# Single file
changelogithub --assets dist/app.js

# Multiple files
changelogithub --assets dist/app.js dist/app.css

# Glob pattern
changelogithub --assets 'dist/*.{js,css,wasm}'

# Multiple patterns
changelogithub --assets 'dist/*.js' --assets 'build/*.tar.gz'
```

--------------------------------

### Resolve configuration using library

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Use the `resolveConfig` function to programmatically resolve the changelogithub configuration, including git references and repository details.

```typescript
import { resolveConfig } from 'changelogithub'

const config = await resolveConfig({
  token: process.env.GITHUB_TOKEN
})

console.log(config.from)  // Previous tag
console.log(config.to)    // Current tag
console.log(config.repo)  // owner/repo
```

--------------------------------

### Create Release

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/endpoints.md

Creates a new GitHub release with specified tag, name, and content. Supports draft and prerelease options.

```APIDOC
## POST /repos/{owner}/{repo}/releases

### Description
Create a new GitHub release with changelog content.

### Method
POST

### Endpoint
`/repos/{owner}/{repo}/releases`

### Parameters
#### Request Body
- **tag_name** (string) - Required - Git tag to release (must exist)
- **name** (string) - Optional - Display name for release
- **body** (string) - Optional - Release notes in Markdown
- **draft** (boolean) - Optional - Create as draft
- **prerelease** (boolean) - Optional - Mark as prerelease

### Request Example
```http
POST https://api.github.com/repos/antfu/changelogithub/releases
Authorization: token ghp_xxxx
Accept: application/vnd.github.v3+json
Content-Type: application/json

{
  "tag_name": "v2.0.0",
  "name": "Version 2.0",
  "body": "## Features\n\n- New feature description",
  "draft": false,
  "prerelease": false
}
```

### Response
#### Success Response (201 Created)
- **id** (integer) - The release ID.
- **url** (string) - The API URL for the release.
- **html_url** (string) - The URL to the release on GitHub.
- **upload_url** (string) - The URL for uploading assets.
- **tag_name** (string) - The name of the tag.
- **name** (string) - The display name of the release.
- **body** (string) - The release notes.
- **draft** (boolean) - Whether the release is a draft.
- **prerelease** (boolean) - Whether the release is a prerelease.
- **created_at** (string) - The timestamp when the release was created.
- **published_at** (string) - The timestamp when the release was published.

#### Response Example
```json
{
  "id": 123456,
  "url": "https://api.github.com/repos/antfu/changelogithub/releases/123456",
  "html_url": "https://github.com/antfu/changelogithub/releases/tag/v2.0.0",
  "upload_url": "https://uploads.github.com/repos/antfu/changelogithub/releases/123456/assets{?name,label}",
  "tag_name": "v2.0.0",
  "name": "Version 2.0",
  "body": "## Features\n\n- New feature description",
  "draft": false,
  "prerelease": false,
  "created_at": "2024-01-01T00:00:00Z",
  "published_at": "2024-01-01T00:00:00Z"
}
```
```

--------------------------------

### Troubleshooting: Tag Not Found on GitHub

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Ensure the tag exists on GitHub by pushing it (`git push origin v1.0.0`). Alternatively, specify the target ref with `--to`.

```bash
# Push the tag
git push origin v1.0.0

# Or specify correct ref
changelogithub --to main
```

--------------------------------

### Fetch Full Git History

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/errors.md

If you encounter 'No commits found' errors due to a shallow clone, use this command to fetch the complete git history.

```bash
# Use full clone
git fetch --unshallow
```

--------------------------------

### Save Changelog to File

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Use the `--output` flag to generate and save the changelog to a file, such as `CHANGELOG.md`, without performing a release.

```bash
# Generate and save, don't release
changelogithub --output CHANGELOG.md
```

--------------------------------

### Upload Release Assets

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/cli.md

Upload specified files as assets to the GitHub release. Glob patterns can be used and must be quoted.

```bash
changelogithub --assets dist/app.js dist/app.css

# Use glob patterns (quoted to prevent shell expansion)
changelogithub --assets 'dist/*.js' 'build/*.tar.gz'

# Multiple asset options
changelogithub --assets dist/ --assets build/
```

--------------------------------

### Format Output with TypeScript

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Use the `generateMarkdown` and `generatePlain` functions to format changelog content. Ensure `commits` and `config` are properly defined before use.

```typescript
import { generateMarkdown, generatePlain } from 'changelogithub'

// Markdown format
const markdown = generateMarkdown(commits, config)

// Plain text format
const plain = generatePlain(commits, config)
```

--------------------------------

### Generate changelog only using library

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Use the `generate` function from the changelogithub library to programmatically generate a changelog, returning the output, commits, and configuration.

```typescript
import { generate } from 'changelogithub'

const { output, commits, config } = await generate({
  token: process.env.GITHUB_TOKEN
})

console.log(`Generated ${commits.length} commits`)
console.log(output)
```

--------------------------------

### Data Flow of Changelog Generation

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/README.md

Illustrates the sequence of operations from user input to the final GitHub release.

```mermaid
graph TD
User Input (CLI/Library)
    ↓
resolveConfig() → Load & merge configuration
    ↓
getGitDiff() → Fetch raw git commits
    ↓
parseCommits() → Parse conventional commits
    ↓
resolveAuthors() → (optional) Fetch GitHub login info
    ↓
generateMarkdown/Plain() → Format output
    ↓
sendRelease() → Create/update GitHub release
    ↓
uploadAssets() → (optional) Upload files to release
```

--------------------------------

### Handle CLI Errors Gracefully

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/errors.md

This code shows how to use a try-catch block when using Changelogithub as a library to gracefully handle potential errors during the changelog generation process.

```typescript
try {
  const result = await generate({
    token: process.env.GITHUB_TOKEN
  })
} catch (error) {
  console.error('Failed to generate changelog:', error)
  // Implement fallback or retry logic
}
```

--------------------------------

### Set GitHub Token Environment Variable

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/errors.md

To resolve 'Token not found' errors, set the GITHUB_TOKEN environment variable with your personal access token or use the --token argument.

```bash
# Set token
export GITHUB_TOKEN=ghp_xxxx
```

```bash
# Or pass as argument
changelogithub --token ghp_xxxx
```

--------------------------------

### join()

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/api-reference/utils.md

Joins array elements with customizable separators and a final glue. Useful for creating natural language lists.

```APIDOC
## join()

### Description
Joins array elements with customizable separators and final glue. Useful for creating natural language lists like "Alice, Bob and Charlie".

### Logic
- **Empty array**: Returns empty string
- **One element**: Returns that element
- **Two elements**: Returns `elem1 + finalGlue + elem2`
- **Three+ elements**: Returns `elem1, elem2, finalGlue + elemN`

### Signature
```typescript
function join(
  array?: string[],
  glue?: string,
  finalGlue?: string
): string
```

### Parameters
#### Path Parameters
- **array** (string[]) - Optional - Array of strings to join
- **glue** (string) - Optional - Separator between items
- **finalGlue** (string) - Optional - Separator before last item

### Return Type
```typescript
string
```
Joined string, or empty string if array is empty/falsy.

### Examples
```typescript
join(['Alice'])                // 'Alice'
join(['Alice', 'Bob'])         // 'Alice and Bob'
join(['Alice', 'Bob', 'Charlie'])  // 'Alice, Bob and Charlie'

// Custom separators
join(['A', 'B', 'C'], ' | ', ' | ')  // 'A | B | C'
join(['A', 'B', 'C'], '; ', '; ')    // 'A; B; C'

// Empty or falsy
join([])        // ''
join(undefined) // ''
join(null)      // ''
```
```

--------------------------------

### List All Git Tags

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/api-reference/git.md

Fetches and returns an array of all git tags in the repository, ordered from most recent to oldest. Useful for iterating through release history.

```typescript
import { getGitTags } from 'changelogithub'

const tags = await getGitTags()
console.log(tags)  // ["v2.0.0", "v1.9.0", "v1.8.0", ...]
```

--------------------------------

### Generate Changelog Function

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/README.md

The main entry point for generating changelogs programmatically. It returns configuration, output, and commit details.

```typescript
generate(options: ChangelogOptions): Promise<{
  config: ResolvedChangelogOptions
  output: string
  commits: Commit[]
}>
```

--------------------------------

### Generate changelog with custom git range

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Specify a custom git range using `from` and `to` options when generating a changelog with the library.

```typescript
const result = await generate({
  from: 'v1.0.0',
  to: 'v2.0.0',
  token: process.env.GITHUB_TOKEN
})
```

--------------------------------

### GitHub Actions - Automatic Release Notes

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/README.md

Automatically generate release notes when a tag is pushed to GitHub. Requires a GITHUB_TOKEN.

```yaml
- run: npx changelogithub
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Generate Changelog

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/INDEX.md

The main generate function is the primary entry point for creating changelogs.

```typescript
import { generate } from 'changelogithub'

await generate({
  // ... generation options
})
```

--------------------------------

### Enable Verbose Git Output

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/errors.md

Use this command to see detailed git command output, which can help in debugging issues related to git operations performed by changelogithub.

```bash
# See git command errors
GIT_TRACE=1 changelogithub
```

--------------------------------

### ChangelogOptions Interface

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/types.md

Defines the configuration options for generating changelogs. It extends partial options from the 'changelogen' library and includes specific settings for GitHub integration, release formatting, and filtering.

```typescript
interface ChangelogOptions extends Partial<ChangelogenOptions> {
  dry?: boolean
  contributors?: boolean
  name?: string
  draft?: boolean
  prerelease?: boolean
  token?: string
  titles?: {
    breakingChanges?: string
  }
  capitalize?: boolean
  group?: boolean | 'multiple'
  emoji?: boolean
  baseUrl?: string
  baseUrlApi?: string
  tagFilter?: (tag: string) => boolean
  releaseRepo?: RepoConfig | string
  tag?: string
  assets?: string[] | string
  style?: 'markdown' | 'plain'
}
```

--------------------------------

### Release to Different GitHub Repository

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Specify different repositories for the changelog source and release target using `--github` and `--release-github`. Useful for monorepos.

```bash
# Useful for monorepos or separate release repos
changelogithub --github owner/main --release-github owner/releases
```

--------------------------------

### Troubleshooting: Invalid GitHub Token

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/quick-reference.md

Verify your GitHub token by testing it with `curl`. If invalid, pass a valid token using the `--token` flag.

```bash
# Check token is valid
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user

# Pass token explicitly
changelogithub --token ghp_xxxx
```

--------------------------------

### Custom GitHub Repository

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/cli.md

Specify a different GitHub repository (owner/repo) for generating the changelog.

```bash
changelogithub --github owner/other-repo
```

--------------------------------

### Generate Changelog in GitHub Actions

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/errors.md

This snippet shows how to run the changelogithub CLI within a GitHub Actions workflow. It includes setting the GITHUB_TOKEN environment variable and an optional setting to continue the pipeline even if the action fails.

```yaml
- name: Generate changelog
  run: npx changelogithub
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  continue-on-error: true  # Optional: continue pipeline on error
```

--------------------------------

### Utility Functions

Source: https://github.com/antfu/changelogithub/blob/main/_autodocs/INDEX.md

A collection of general-purpose utility functions for string manipulation and array grouping, including `capitalize`, `groupBy`, `join`, and a regex for emoji detection.

```APIDOC
## Utility Functions

### Description
Provides general utility functions.

### Functions
- `capitalize()`: Capitalizes a string.
- `groupBy()`: Groups an array by a property.
- `join()`: Joins an array with custom separators.
- `emojisRE`: Regular expression for emoji detection.

### Examples
```js
// Example: Capitalize string
const capitalized = capitalize('hello');

// Example: Group array
const grouped = groupBy(items, 'category');
```
```