### Install auto-changelog Locally

Source: https://github.com/cookpete/auto-changelog/blob/master/CONTRIBUTING.md

Clone the repository and install dependencies using yarn or npm.

```bash
git clone https://github.com/CookPete/auto-changelog.git
cd auto-changelog
yarn # or npm install
```

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

### Get Git Version with getGitVersion

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/utils.md

Retrieves the installed Git version. Returns a promise that resolves with the version string (e.g., '2.40.0') or null if Git is not found. Useful for compatibility checks.

```javascript
const { getGitVersion } = require('auto-changelog/src/utils');

const version = await getGitVersion();
console.log(version); // "2.40.0"

// Used for compatibility checks
if (semver.gte(version, '1.7.2')) {
  // Use modern git format
}
```

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

### Catch Handlebars Setup File Errors

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/errors.md

Handle errors when loading or executing the Handlebars setup file. Ensure the file exists, has correct syntax, and exports a function.

```javascript
try {
  await run(process.argv);
} catch (error) {
  if (error.code === 'MODULE_NOT_FOUND') {
    console.error('Setup file not found');
  }
}
```

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

### Install auto-changelog

Source: https://github.com/cookpete/auto-changelog/blob/master/README.md

Install auto-changelog as a development dependency using npm or yarn.

```bash
npm install auto-changelog --save-dev
```

```bash
yarn add auto-changelog --dev
```

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

### Load Plugin with npm

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/INDEX.md

Install and load an Auto-Changelog plugin, such as `auto-changelog-contributor`, using npm and the command line or configuration.

```bash
npm install auto-changelog-contributor
auto-changelog --plugins contributor
```

```json
{
  "auto-changelog": {
    "plugins": ["contributor"]
  }
}
```

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

### Configuration Merge Example

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/configuration.md

Illustrates how configuration options are merged from different sources, with later sources overriding earlier ones. This shows the final resulting configuration object.

```javascript
// Built-in defaults
{ output: 'CHANGELOG.md', template: 'compact' }

// + .auto-changelog file
{ output: 'HISTORY.md' }

// + package.json config
{ template: 'keepachangelog' }

// + CLI arguments
{ unreleased: true }

// = Final result
{
  output: 'HISTORY.md',
  template: 'keepachangelog',
  unreleased: true,
  // ... other defaults
}
```

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

### Setup custom Handlebars helpers

Source: https://github.com/cookpete/auto-changelog/blob/master/README.md

Provide a JavaScript file to `--handlebars-setup` to register custom Handlebars helpers. These helpers can then be used within custom templates.

```javascript
auto-changelog --handlebars-setup setup.js --template custom-template.hbs

// setup.js
module.exports = function (Handlebars) {
  Handlebars.registerHelper('custom', function (context, options) {
    return 'custom helpers!'
  })
}
```

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

### Configure auto-changelog in .auto-changelog file

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/run.md

Example of a .auto-changelog JSON configuration file for project-level settings.

```json
{
  "output": "HISTORY.md",
  "template": "keepachangelog",
  "hideEmptyReleases": true
}
```

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

### getStartIndex

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/tags.md

Calculates the starting index for changelog content based on `endingVersion` in the provided options.

```APIDOC
## getStartIndex(tags, options)

### Description
Calculates the starting index for changelog content based on `endingVersion`.

### Parameters
- **tags** (Tag[]) - An array of tag objects.
- **options** (Object) - An object that may contain an `endingVersion` property.

### Returns
- `number` - The index of the tag matching `options.endingVersion`, or 0 if not found.
```

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

### inferSemver examples

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/tags.md

Demonstrates how inferSemver converts incomplete version strings to valid semver by adding missing .0 components. Useful for standardizing version formats.

```javascript
const { inferSemver } = require('auto-changelog/src/tags');
inferSemver('v2');        // Returns 'v2.0.0'
inferSemver('1.5');       // Returns '1.5.0'
```

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

### Calculate Tag Start Index

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/tags.md

Calculates the starting index for changelog content based on `endingVersion`. Returns the index of the tag matching `options.endingVersion`, or 0 if not found.

```javascript
getStartIndex(tags: Tag[], options: Object): number
```

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

### Example Usage of Remote URL Overrides

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/remote.md

Demonstrates setting up custom remote URL generators using an options object. This can be used even when a git remote is not explicitly configured.

```javascript
const remoteOptions = {
  commitUrl: 'https://internal.company.com/git/commits/{id}',
  issueUrl: 'https://jira.company.com/browse/{id}',
  compareUrl: 'https://internal.company.com/git/compare/{from}...{to}'
};

const remote = getRemote('', remoteOptions);
// Results in custom URL generators even without git remote
```

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

### Setup Custom Handlebars Helpers and Partials

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/configuration.md

Provide a JavaScript file to register custom Handlebars helpers and partials. This allows for advanced template customization.

```javascript
module.exports = function (Handlebars) {
  Handlebars.registerHelper('upper', str => (str || '').toUpperCase());
  Handlebars.registerPartial('header', 'My Header');
};
```

```bash
auto-changelog --handlebars-setup ./helpers.js --template custom.hbs
```

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

### Install auto-changelog Globally

Source: https://github.com/cookpete/auto-changelog/blob/master/README.md

Install the auto-changelog package globally using npm. This makes the command-line tool available system-wide.

```bash
npm install -g auto-changelog
```

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

### getGitVersion()

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/utils.md

Retrieves the installed Git version, returning a semver-formatted string or null if Git is not found.

```APIDOC
## getGitVersion()

### Description
Retrieves the installed git version. Returns a Promise that resolves with the version string (e.g., "2.40.0") or null if Git is not found.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
None (JavaScript function)

### Endpoint
None (JavaScript function)

### Parameters
None

### Request Example
```javascript
const { getGitVersion } = require('auto-changelog/src/utils');

const version = await getGitVersion();
console.log(version);
```

### Response
#### Success Response (Promise<string | null>)
Resolves with the Git version string or null.

#### Response Example
```javascript
'2.40.0'
null
```
```

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

### Filter by Date Range and Version

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/INDEX.md

Generates a changelog filtered by a starting date and an ending version.

```bash
auto-changelog --starting-date 2024-01-01 --ending-version v2.0.0
```

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

### Example Custom Helpers for Text Transformation

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/template.md

Provides example custom Handlebars helpers for transforming text, such as converting strings to uppercase and conditionally rendering content based on release type.

```javascript
// setup.js
module.exports = function (Handlebars) {
  Handlebars.registerHelper('upper', function (str) {
    return (str || '').toUpperCase();
  });

  Handlebars.registerHelper('if-major', function (release, options) {
    return release.major ? options.fn(this) : options.inverse(this);
  });
};
```

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

### Custom Handlebars Template Example

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/INDEX.md

Example of a custom Handlebars template for generating changelog entries. It iterates through releases, merges, and commits, providing access to their properties. Use this to define your desired changelog format.

```handlebars
{{#each releases}}
  ### [{{title}}]({{href}})
  {{niceDate}}
  
  {{#each merges}}
    - {{message}} [#{{id}}]({{href}})
  {{/each}}
  
  {{#each commits}}
    - {{subject}} [{{shorthash}}]({{href}})
  {{/each}}
{{/each}}
```

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

### getGitVersion

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/utils.md

Retrieves the installed Git version.

```APIDOC
## getGitVersion

### Description
Retrieves the installed Git version.

### Parameters
(No parameters specified in source)

### Request Example
(Example not provided in source)

### Response
(Response details not provided in source)
```

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

### Register Custom Handlebars Helper and Partial

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/template.md

Demonstrates how to register a custom helper and a partial within a setup file for auto-changelog. This is useful for extending template functionality.

```bash
auto-changelog --handlebars-setup ./setup.js --template custom.hbs
```

```javascript
module.exports = function (Handlebars) {
  Handlebars.registerHelper('custom-helper', function (context, options) {
    // Helper logic here
    return 'output';
  });

  Handlebars.registerPartial('partial-name', 'Partial content');
};
```

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

### Run Auto-Changelog Programmatically

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/INDEX.md

Use the `run` function from `auto-changelog/src/run` to execute the changelog generation programmatically. This example demonstrates passing options as an array of strings, similar to CLI arguments.

```javascript
const { run } = require('auto-changelog/src/run');

await run(['node', 'auto-changelog', '--template', 'compact']);
```

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

### SSH and HTTPS Remote URL Formats

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/remote.md

Examples of valid remote repository URLs in both HTTPS and SSH formats.

```plaintext
https://github.com/user/repo.git
https://gitlab.com/group/project.git
```

```plaintext
git@github.com:user/repo.git
git@gitlab.com:group/project.git
```

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

### Run Tests

Source: https://github.com/cookpete/auto-changelog/blob/master/CONTRIBUTING.md

Execute the test suite using yarn or npm. Consider adding new tests.

```bash
yarn test # or npm test
```

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

### Date Formatting Utility

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/tags.md

Demonstrates the usage of the `niceDate()` utility for formatting ISO dates into a human-readable format.

```APIDOC
## Date Formatting

Uses `niceDate()` utility to format ISO dates to human-readable form:

```
"2024-06-25" → "25 June 2024"
```
```

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

### Set Earliest Version for Changelog

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/configuration.md

Configure `startingVersion` to specify the earliest version tag to include in the changelog. Versions prior to this will be excluded.

```bash
auto-changelog --starting-version v1.0.0

```

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

### Run auto-changelog

Source: https://github.com/cookpete/auto-changelog/blob/master/CONTRIBUTING.md

Execute the auto-changelog project using Node.js.

```bash
node src/index.js
```

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

### getEndIndex

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/tags.md

Calculates the ending index for changelog content based on various starting constraints defined in the options.

```APIDOC
## getEndIndex(tags, options)

### Description
Calculates the ending index for changelog content based on starting constraints.

### Parameters
- **tags** (Tag[]) - An array of tag objects.
- **options** (Object) - An object that may contain filtering options like `unreleasedOnly`, `startingVersion`, or `startingDate`.

### Returns
- `number` - The calculated ending index based on the provided options.
```

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

### Use Individual Auto-Changelog Modules

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/INDEX.md

For more granular control, import and use individual modules like `fetchTags`, `fetchCommits`, `parseReleases`, `compileTemplate`, and `fetchRemote`. This allows for custom processing and integration. Ensure all necessary options are provided.

```javascript
const { fetchTags } = require('auto-changelog/src/tags');
const { fetchCommits } = require('auto-changelog/src/commits');
const { parseReleases } = require('auto-changelog/src/releases');
const { compileTemplate } = require('auto-changelog/src/template');
const { fetchRemote } = require('auto-changelog/src/remote');

const options = {
  tagPrefix: 'v',
  getCommitLink: hash => `https://github.com/user/repo/commit/${hash}`,
  // ... more options
};

const remote = await fetchRemote(options);
const tags = await fetchTags({ ...options, ...remote });
const releases = await parseReleases(tags, { ...options, ...remote });
const changelog = await compileTemplate(releases, options);
```

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

### isLink(string)

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/utils.md

Tests if a given string is a URL, returning true if it starts with 'http://' or 'https://'.

```APIDOC
## isLink(string)

### Description
Tests if a string is a URL. Returns true if string starts with `http://` or `https://`.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
None (JavaScript function)

### Endpoint
None (JavaScript function)

### Parameters
* **string** (string) - Required - The string to test.

### Request Example
```javascript
const { isLink } = require('auto-changelog/src/utils');

isLink('https://github.com/user/repo');
isLink('http://example.com');
isLink('ftp://files.com');
isLink('#123');
```

### Response
#### Success Response (boolean)
Returns true if the string is a URL, false otherwise.

#### Response Example
```javascript
true
true
false
false
```
```

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

### Configuration Loading Priority

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/configuration.md

Configuration options are loaded in a specific order, with later sources overriding earlier ones. This ensures command-line arguments have the highest precedence.

```text
Built-in defaults
    ↓
.auto-changelog file (JSON)
    ↓
package.json auto-changelog section
    ↓
Command-line arguments (highest priority)
    ↓
Final merged options
```

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

### Test if String is URL with isLink

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/utils.md

Tests if a given string is a URL by checking if it starts with 'http://' or 'https://'.

```javascript
const { isLink } = require('auto-changelog/src/utils');

isLink('https://github.com/user/repo');    // true
isLink('http://example.com');              // true
isLink('ftp://files.com');                 // false
isLink('#123');                            // false
```

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

### Prepend Changelog to File

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/configuration.md

Insert the generated changelog at the beginning of a specified output file. If the file does not exist, it will be created. If the file contains the '<!-- auto-changelog-above -->' marker, the changelog will be inserted above it.

```bash
auto-changelog --prepend
```

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

### cmd

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/utils.md

Executes a shell command using child_process.spawn. Wraps command execution for integration.

```APIDOC
## cmd

### Description
Executes a shell command using child_process.spawn.

### Parameters
(Specific parameters not detailed in source, refer to library usage for details)

### Request Example
(Example not provided in source)

### Response
(Response details not provided in source)
```

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

### isValidTag with custom pattern

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/tags.md

Use isValidTag with a custom tagPattern to validate tags against a specific regex. This example shows validation for tags matching 'build-\d+'.

```javascript
// With custom tag pattern
const validate = isValidTag({ tagPattern: 'build-\d+' });
validate({ tag: 'build-12345', version: null }); // true
validate({ tag: 'v1.0.0', version: '1.0.0' });   // false
```

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

### CLI Usage

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/INDEX.md

The primary entry point for the auto-changelog tool is its executable CLI. Options are documented separately.

```APIDOC
## CLI Usage

### Description

The primary entry point is the executable CLI.

### Command

```bash
auto-changelog [options]
```

### Options

Options documented in [configuration.md](configuration.md).
```

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

### Calculate Tag End Index

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/tags.md

Calculates the ending index for changelog content based on starting constraints. Respects options like `unreleasedOnly`, `startingVersion`, and `startingDate`.

```javascript
getEndIndex(tags: Tag[], options: Object): number
```

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

### run(argv)

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/run.md

The main asynchronous function that orchestrates the entire changelog generation process. It parses arguments, loads configuration, fetches git tags, parses releases, compiles the template, and writes the output.

```APIDOC
## run(argv)

### Description
Main async function that orchestrates the entire changelog generation process. Parses arguments, loads configuration, fetches git tags, parses releases, compiles the template, and writes output.

### Parameters
#### Path Parameters
- **argv** (string[]) - Required - Command-line arguments array (typically `process.argv`)

### Return type
`Promise<void>` - Resolves when changelog has been successfully written or output to stdout.

### Throws
- Error if configuration file cannot be read
- Error if git commands fail
- Error if output file cannot be written (unless using `--stdout`)

### Example
```javascript
const { run } = require('auto-changelog').run;
await run(process.argv);
```
```

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

### Custom Compare URL Template

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/configuration.md

Set a URL template for version comparison links. Use {from} for the earlier tag and {to} for the later tag.

```bash
auto-changelog --compare-url "https://github.com/user/repo/compare/{from}...{to}"
```

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

### isValidTag with default semver validation

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/tags.md

Use isValidTag with an empty options object to perform default semver validation. This example shows validation for tags that are valid semver versions.

```javascript
// With default semver validation
const validate = isValidTag({});
validate({ tag: 'v1.0.0', version: '1.0.0' });   // true
validate({ tag: 'build-12345', version: null }); // false
```

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

### Compile Template with Release Data

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/template.md

Use this function to compile a Handlebars template with release data and options. It supports built-in, local, and remote templates, and can integrate custom Handlebars helpers via a setup file.

```javascript
const { compileTemplate } = require('auto-changelog/src/template');

// Using built-in template
const changelog = await compileTemplate(releases, {
  template: 'compact'
});

// Using custom local template
const changelog = await compileTemplate(releases, {
  template: './my-template.hbs'
});

// Using remote template
const changelog = await compileTemplate(releases, {
  template: 'https://example.com/templates/custom.hbs'
});

// With custom Handlebars helpers
const changelog = await compileTemplate(releases, {
  template: 'compact',
  handlebarsSetup: './handlebars-helpers.js'
});
```

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

### Run Auto-Changelog via CLI

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/INDEX.md

The primary entry point for auto-changelog is its executable CLI. Options are documented separately.

```bash
auto-changelog [options]
```

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

### Core Processing Pipeline Overview

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/README.md

Illustrates the sequence of operations in the auto-changelog core processing pipeline, from fetching remote data to compiling the final markdown output.

```text
run.js (orchestration)
  ↓
  fetchRemote() → link generators
  fetchTags() → git tags with metadata
  parseReleases() → aggregated commits by release
    ↓
    fetchCommits() for each tag range
      ↓
      parseCommit() → hash, author, message
      getFixes() → issue references
      getMerge() → PR information
  ↓
  compileTemplate() → markdown output
```

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

### Configure auto-changelog in .auto-changelog file

Source: https://github.com/cookpete/auto-changelog/blob/master/README.md

Alternatively, store configuration options in a root-level .auto-changelog file. Options in package.json take precedence over this file.

```json
{
  "output": "HISTORY.md",
  "template": "keepachangelog",
  "unreleased": true,
  "commitLimit": false
}
```

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

### Load Plugins

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/configuration.md

Specify an array of plugin names to load. Plugins are loaded from `auto-changelog-{name}` packages and can hook into commit processing.

```bash
auto-changelog --plugins contributor changelog-contributors
```

```json
{
  "plugins": ["contributor", "changelog-contributors"]
}
```

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

### Use Custom Changelog Template

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/configuration.md

Specify a template for rendering the changelog. Built-in templates like 'compact' and 'keepachangelog' are available, or you can provide a path to a local Handlebars file or a remote URL.

```bash
auto-changelog --template keepachangelog
```

```bash
auto-changelog --template ./custom.hbs
```

```bash
auto-changelog --template https://example.com/changelog.hbs
```

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

### Set Earliest Date for Changelog

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/configuration.md

Use `startingDate` to define the earliest date (YYYY-MM-DD format) for commits to be included in the changelog.

```bash
auto-changelog --starting-date 2024-01-01

```

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

### Use an external custom template via URL

Source: https://github.com/cookpete/auto-changelog/blob/master/README.md

Point to a Handlebars template hosted online using a URL with the `--template` option.

```bash
auto-changelog --template https://example.com/templates/compact.hbs
```

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

### Fetch Git Tags with Options

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/tags.md

Fetches git tags from the repository and enriches them with release metadata. Supports semver validation, custom tag patterns, and creates an "Unreleased" or version entry if needed. Configure options like tag prefix, unreleased section inclusion, and custom compare link generation.

```javascript
const { fetchTags } = require('auto-changelog/src/tags');

const tags = await fetchTags({
  tagPrefix: 'v',
  unreleased: true,
  getCompareLink: (from, to) => `https://github.com/user/repo/compare/${from}...${to}`
});

// Returns array like:
// [
//   {
//     tag: null,
//     title: 'Unreleased',
//     date: '2024-06-25T00:00:00.000Z',
//     href: 'https://github.com/user/repo/compare/v1.2.3...HEAD',
//     version: null,
//     ...
//   },
//   {
//     tag: 'v1.2.3',
//     title: 'v1.2.3',
//     date: '2024-06-20T00:00:00.000Z',
//     version: '1.2.3',
//     ...
//   }
// ]
```

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

### Lint Code with Standard

Source: https://github.com/cookpete/auto-changelog/blob/master/CONTRIBUTING.md

Run the linter to check code style. Fix any issues that arise.

```bash
yarn lint # or npm run lint
```

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

### Use Release Summary

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/configuration.md

Enable this option to use the body of the tagged commit message as a release summary. Content after the first blank line is extracted and appears in the release header.

```bash
auto-changelog --release-summary
```

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

### Programmatic Usage - Individual Modules

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/INDEX.md

Import and use individual modules for more granular control over the changelog generation steps.

```APIDOC
## Programmatic Usage - Individual Modules

### Description

Import and use individual modules for more granular control over the changelog generation steps. This allows for custom workflows by composing different functionalities.

### Modules

- **`fetchTags`**: Fetches Git tags.
- **`fetchCommits`**: Fetches Git commits.
- **`parseReleases`**: Parses fetched tags and commits into release data.
- **`compileTemplate`**: Compiles the release data into a changelog string using a specified template.
- **`fetchRemote`**: Fetches remote repository information, useful for generating links.

### Example Usage

```javascript
import {
  fetchTags,
  fetchCommits,
  parseReleases,
  compileTemplate,
  fetchRemote
} from 'auto-changelog/src/tags';

const options = {
  tagPrefix: 'v',
  getCommitLink: hash => `https://github.com/user/repo/commit/${hash}`,
  // ... more options
};

const remote = await fetchRemote(options);
const tags = await fetchTags({ ...options, ...remote });
const releases = await parseReleases(tags, { ...options, ...remote });
const changelog = await compileTemplate(releases, options);
```
```

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

### Specify tag prefix

Source: https://github.com/cookpete/auto-changelog/blob/master/README.md

Use the --tag-prefix option if your version tags are prefixed with a specific string, such as a package name in a monorepo.

```bash
# When all versions are tagged like my-package/1.2.3
auto-changelog --tag-prefix my-package/
```

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

### cmd(string, onProgress)

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/utils.md

Executes a shell command, capturing its stdout output as a string. It supports an optional progress callback to track bytes received.

```APIDOC
## cmd(string, onProgress)

### Description
Executes a shell command and returns stdout output as string. Supports an optional callback for progress updates.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
None (JavaScript function)

### Endpoint
None (JavaScript function)

### Parameters
* **string** (string) - Required - Command string (space-separated, single argument).
* **onProgress** (Function) - Optional - Callback function: `(bytesReceived: number) => void`.

### Request Example
```javascript
const { cmd } = require('auto-changelog/src/utils');

const tags = await cmd('git tag -l');
const log = await cmd('git log --oneline', (bytes) => {
  console.log(`Received ${bytes} bytes`);
});
```

### Response
#### Success Response (Promise<string>)
Resolves with the complete stdout output of the command.

#### Response Example
```javascript
'commit 1\ncommit 2'
```
```

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

### Generate Changelog with Custom Output and Template

Source: https://github.com/cookpete/auto-changelog/blob/master/README.md

Specify a custom output file name (HISTORY.md) and use the 'keepachangelog' template for the generated changelog.

```bash
auto-changelog --output HISTORY.md --template keepachangelog
```

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

### Run Changelog Generation

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/run.md

Execute the main changelog generation function with provided command-line arguments. This function handles parsing, configuration, git operations, templating, and output writing. It resolves when the changelog is successfully written or output to stdout.

```javascript
const { run } = require('auto-changelog').run;
await run(process.argv);
```

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

### Import Core auto-changelog Modules

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/README.md

Import necessary functions from the auto-changelog library for programmatic use. Ensure these modules are available in your project.

```javascript
const { run } = require('auto-changelog/src/run');
const { fetchTags } = require('auto-changelog/src/tags');
const { parseReleases } = require('auto-changelog/src/releases');
```

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

### Specify Config File

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/configuration.md

Use this option to specify a custom location for the auto-changelog configuration file.

```bash
auto-changelog --config ./config/changelog.json
```

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

### Use a local custom template

Source: https://github.com/cookpete/auto-changelog/blob/master/README.md

Specify a local Handlebars template file using the `--template` option to customize the changelog output.

```bash
auto-changelog --template changelog-template.hbs
```

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

### Generate changelog data as JSON

Source: https://github.com/cookpete/auto-changelog/blob/master/README.md

Output the changelog data in JSON format using `--template json` and `--output` to a file. This is useful for inspecting the data passed to templates.

```bash
auto-changelog --template json --output changelog-data.json
```

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

### Enable Detailed Output with JSON Template

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/errors.md

Use this command to write intermediate data to stdout for debugging. This is useful for inspecting the data before it's rendered into a changelog.

```bash
auto-changelog --template json
```

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

### BitBucket Link Formats

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/remote.md

Outlines the URL structure for commits, issues, and pull requests on BitBucket. Note the reversed order of 'from' and 'to' in the compare URL.

```text
Commit:  {protocol}//{hostname}/{repo}/commits/{hash}
Issue:   {protocol}//{hostname}/{repo}/issues/{id}
PR:      {protocol}//{hostname}/{repo}/pull-requests/{id}
Compare: {protocol}//{hostname}/{repo}/compare/{to}..{from}
```

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

### Custom Issue Tracker Configuration (Jira)

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/INDEX.md

Configure Auto-Changelog to link issues to a custom tracker like Jira using command-line arguments or a configuration file.

```bash
auto-changelog \
  --issue-pattern "[A-Z]+-\d+" \
  --issue-url "https://jira.mycompany.com/browse/{id}"
```

```json
{
  "auto-changelog": {
    "issuePattern": "[A-Z]+-\d+",
    "issueUrl": "https://jira.mycompany.com/browse/{id}"
  }
}
```

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

### Catch File Not Found Error

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/errors.md

Catch errors when the specified package file does not exist. Verify the file path and ensure the file exists.

```javascript
try {
  await run(process.argv);
} catch (error) {
  if (error.message.includes('does not exist')) {
    console.error('Package file not found');
  }
}
```

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

### Main Configuration Object

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/types.md

The primary configuration object, merged from CLI arguments, config files, and package.json. It encompasses a wide range of options for controlling output, templating, Git operations, versioning, commit filtering, issue tracking, and more. Use this object to customize the behavior of the application.

```javascript
{
  // Output options
  output: string,
                  // Output file path (default: "CHANGELOG.md")
  stdout: boolean,
                 // Write to stdout instead of file
  prepend: boolean,
                // Prepend to existing file instead of replacing
  
  // Template options
  template: string,
                // Template name or file path (default: "compact")
  handlebarsSetup: string,
         // Path to Handlebars setup file
  
  // Git options
  remote: string,
                 // Git remote name (default: "origin")
  appendGitLog: string,
            // Extra arguments for git log
  appendGitTag: string,
            // Extra arguments for git tag
  
  // Version/Tag options
  tagPrefix: string,
                // Prefix to strip from tags (default: "")
  tagPattern: string,
               // Custom regex for matching tags
  latestVersion: string,
           // Explicit latest version
  package: boolean | string,
       // Use version from package.json or file
  unreleased: boolean,
             // Include unreleased section
  unreleasedOnly: boolean,
         // Only show unreleased changes
  
  // Date/Range options
  startingVersion: string,
         // Earliest version to include
  startingDate: string,
            // Earliest date (yyyy-mm-dd) to include
  endingVersion: string,
           // Latest version to include
  
  // Commit filtering options
  commitLimit: number | false,
     // Max commits per release (false = all)
  backfillLimit: number,
           // Max commits for empty releases
  commitPattern: string,
           // Include only matching commits
  ignoreCommitPattern: string,
       // Exclude matching commits
  sortCommits: string,
             // Sort by: relevance, date, date-desc, subject, subject-desc
  
  // Issue/Fix options
  issuePattern: string,
            // Regex for issue references
  issueUrl: string,
            // URL template for issues
  breakingPattern: string,
         // Regex for breaking changes
  
  // Merge options
  mergePattern: string,
            // Custom regex for merge commits
  mergeUrl: string,
                // URL template for merges
  
  // Comparison options
  commitUrl: string,
               // URL template for commits
  compareUrl: string,
              // URL template for version comparisons
  
  // Display options
  hideEmptyReleases: boolean,
       // Omit releases with no content
  hideCredit: boolean,
             // Hide auto-changelog credit line
  releaseSummary: boolean,
         // Include release summary from tagged commit
  
  // Monorepo options
  autodetectMonorepoDisabled: boolean,
 // Disable monorepo detection
  stripTagPrefix: boolean,
         // Strip prefix from release titles
  
  // Text replacement
  replaceText: object,
             // Key-value pairs for regex replacements
  
  // Plugin system
  plugins: Plugin[],
               // Plugin instances
  
  // Config file
  config: string,
                  // Config file location (default: ".auto-changelog")
  
  // Link generation functions (added by remote module)
  getCommitLink: Function,
         // (hash: string) => string | null
  getIssueLink: Function,
          // (id: string) => string | null
  getMergeLink: Function,
          // (id: string) => string | null
  getCompareLink: Function
         // (from: string, to: string) => string | null
}
```

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

### inferSemver(tag)

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/tags.md

Converts incomplete version strings into valid semver format by appending necessary `.0` components.

```APIDOC
## inferSemver(tag)

Converts incomplete version strings to valid semver by adding `.0` components.

```javascript
inferSemver(tag: string): string
```

| Input | Output |
|-------|--------|
| `v1` | `v1.0.0` |
| `1` | `1.0.0` |
| `v1.2` | `v1.2.0` |
| `1.2.3` | `1.2.3` |
| `v1.2.3-alpha` | `v1.2.3-alpha` |

**Example:**

```javascript
const { inferSemver } = require('auto-changelog/src/tags');
inferSemver('v2');        // Returns 'v2.0.0'
inferSemver('1.5');       // Returns '1.5.0'
```

**Source:** `src/tags.js:119-129`
```

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

### Programmatic Usage - Run Function

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/INDEX.md

Use the `run` function for programmatic execution of the changelog generation process.

```APIDOC
## Programmatic Usage - run()

### Description

Use the `run` function for programmatic execution of the changelog generation process. It accepts an array of arguments similar to how the CLI would receive them.

### Method

```javascript
import { run } from 'auto-changelog/src/run';

await run(['node', 'auto-changelog', '--template', 'compact']);
```
```

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

### Specify tag pattern

Source: https://github.com/cookpete/auto-changelog/blob/master/README.md

Use the --tag-pattern option with a regex if your version tags do not follow standard semver or if you want to include all tags as releases.

```bash
# When all versions are tagged like build-12345
auto-changelog --tag-pattern build-\d+
```

```bash
# Include any tag as a release
auto-changelog --tag-pattern .+
```

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

### Generate Changelog with Latest Version

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/INDEX.md

Generates a changelog using the latest version, either by reading from package.json or by explicitly specifying the version.

```bash
# Use version from package.json
auto-changelog --package

# Or specify explicitly
auto-changelog --latest-version 2.5.0
```

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

### fetchCommits(diff, options)

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/commits.md

Executes the `git log` command with detailed output formatting and parses the resulting commit history. It returns a promise that resolves to an array of parsed commit objects.

```APIDOC
## fetchCommits(diff, options)

### Description
Executes `git log` command with detailed output formatting and parses the resulting commit history.

### Parameters
#### Path Parameters
- **diff** (string) - Required - Git diff range (e.g., `v1.0.0..v2.0.0` or `HEAD`)
- **options** (Options) - Optional - Configuration object for parsing behavior

### Options object properties:
#### Parameters
- **getCommitLink** (function) - Function to generate commit URL from hash
- **getIssueLink** (function) - Function to generate issue URL from issue ID
- **getMergeLink** (function) - Function to generate PR/merge URL from ID
- **issuePattern** (string) - Custom regex to match issue references
- **breakingPattern** (string) - Regex to identify breaking change commits
- **mergePattern** (string) - Custom regex for merge commit detection
- **commitPattern** (string) - Include only commits matching this regex
- **ignoreCommitPattern** (string) - Exclude commits matching this regex
- **appendGitLog** (string) - Additional args to pass to git log
- **replaceText** (object) - Key/value pairs for text replacement in messages

### Return
- **Promise<Commit[]>** - Array of parsed commit objects

### Throws:
- Error if git log command fails

### Example
```javascript
const { fetchCommits } = require('auto-changelog/src/commits');

const commits = await fetchCommits('v1.0.0..v2.0.0', {
  getCommitLink: hash => `https://github.com/user/repo/commit/${hash}`,
  getIssueLink: id => `https://github.com/user/repo/issues/${id}`,
  breakingPattern: 'Breaking change'
});

// Returns array like:
// [
//   {
//     hash: '2401ee4706e94629f48830bab9ed5812c032734a',
//     shorthash: '2401ee4',
//     subject: 'Add new feature',
//     message: 'Add new feature\n\nFixes #123',
//     author: 'John Doe',
//     email: 'john@example.com',
//     date: '2024-06-25T10:30:00.000Z',
//     fixes: [{ id: '123', href: '...', author: 'John Doe' }],
//     breaking: false,
//     merge: null,
//     ...
//   }
// ]
```
```

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

### Link to Custom Issue Tracker

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/configuration.md

Configure a custom URL template for linking to issues in external trackers. The `{id}` placeholder will be replaced with the extracted issue identifier.

```bash
# Link to Jira
auto-changelog --issue-url "https://jira.company.com/browse/{id}"

# Link to custom issue tracker
auto-changelog --issue-url "https://bugs.example.com/view.php?id={id}"
```

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

### Template Data Structure for Releases and Options

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/template.md

Illustrates the primary data structure passed to Handlebars templates, including an array of release objects and the configuration options object.

```javascript
{
  releases: Release[],  // Array of release objects
  options: Options      // Configuration object
}
```

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

### Use Package.json Version as Latest

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/configuration.md

The `package` option allows using the version from `package.json` or a specified file as the latest release. This is useful for integration with npm version scripts.

```bash
auto-changelog --package

```

```bash
auto-changelog --package ./package.json

```

```bash
auto-changelog --package ./VERSION

```

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

### Fetch Remote Configuration

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/remote.md

Asynchronously reads the git remote URL and generates link functions based on provided options. Use this to configure link generation for a specific remote.

```javascript
const { fetchRemote } = require('auto-changelog/src/remote');

const remote = await fetchRemote({ remote: 'origin' });

console.log(remote.getCommitLink('abc123def'));
// 'https://github.com/user/repo/commit/abc123def'

console.log(remote.getIssueLink('42'));
// 'https://github.com/user/repo/issues/42'

console.log(remote.getCompareLink('v1.0.0', 'v2.0.0'));
// 'https://github.com/user/repo/compare/v1.0.0...v2.0.0'
```

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

### Use Custom Changelog Templates

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/INDEX.md

Configures auto-changelog to use custom templates for generating the changelog. Supports built-in, local file, and remote URL templates.

```bash
# Built-in templates
auto-changelog --template keepachangelog
auto-changelog --template json

# Local file
auto-changelog --template ./custom.hbs

# Remote URL
auto-changelog --template https://example.com/template.hbs
```

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

### getTemplate(template)

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/template.md

Async function that retrieves template content from various sources, prioritizing URLs, then local files, and finally built-in templates.

```APIDOC
## getTemplate(template)

### Description
Async function that retrieves template content from various sources.

### Parameters
#### Path Parameters
- **template** (string) - Required - Template name, file path, or HTTPS URL

### Resolution order
1. If template matches URL pattern (`^https?://`) - fetch from URL
2. If template is a file path - read from filesystem
3. Otherwise - look in built-in templates directory for `{template}.hbs`
4. Throw error if template not found

### Example
```javascript
const { getTemplate } = require('auto-changelog/src/template');

// Built-in template
await getTemplate('compact');               // Returns content of templates/compact.hbs

// Local file
await getTemplate('./custom-template.hbs'); // Reads custom-template.hbs from cwd

// Remote
await getTemplate('https://example.com/t.hbs'); // Fetches from URL
```
```

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

### Configure auto-changelog via CLI

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/README.md

Use the command-line interface to configure auto-changelog with specific templates and commit limits. This is useful for quick adjustments or scripting.

```bash
auto-changelog --template keepachangelog --commit-limit false
```

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

### Enable monorepo autodetection

Source: https://github.com/cookpete/auto-changelog/blob/master/README.md

Configure auto-changelog to automatically detect monorepos and derive tag prefixes from package names. This setting will default to false in the next major version.

```json
{
  "auto-changelog": {
    "autodetectMonorepoDisabled": false
  }
}
```

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

### Set Output File Path

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/configuration.md

Specify a file path for the generated changelog. The file is created in the current working directory unless an absolute path is provided. Existing files will be overwritten.

```bash
auto-changelog --output HISTORY.md
```

```json
{ "output": "HISTORY.md" }
```

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

### Generate Basic Changelog

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/INDEX.md

Invokes auto-changelog to generate a changelog from git tags and writes it to CHANGELOG.md.

```bash
auto-changelog
# Reads from git tags, writes to CHANGELOG.md
```

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

### Redirect Changelog to Stdout

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/configuration.md

Write the changelog content directly to standard output instead of a file. This is useful for piping the output to other commands or for immediate viewing.

```bash
auto-changelog --stdout > CHANGELOG.md
```

```bash
auto-changelog --stdout | less
```

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

### Format Date

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/tags.md

Formats ISO dates to a human-readable string using the `niceDate()` utility.

```text
"2024-06-25" → "25 June 2024"
```

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

### compileTemplate(releases, options)

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/template.md

Main async function that compiles a Handlebars template with release data and returns the rendered changelog. It supports built-in templates, local files, and remote URLs, and can utilize custom Handlebars helpers.

```APIDOC
## compileTemplate(releases, options)

### Description
Main async function that compiles a Handlebars template with release data and returns the rendered changelog.

### Parameters
#### Path Parameters
- **releases** (Release[]) - Required - Array of release objects from `parseReleases()`
- **options** (Options) - Required - Configuration object

#### Request Body
- **template** (string) - Required - Template name (compact, keepachangelog, json), file path, or HTTPS URL
- **handlebarsSetup** (string) - Optional - Path to JS file exporting Handlebars setup function

### Response
#### Success Response (200)
- **Promise<string>** - Rendered changelog markdown

### Throws
- Error if template file not found
- Error if template URL cannot be fetched
- Error if handlebarsSetup file cannot be loaded

### Request Example
```javascript
const { compileTemplate } = require('auto-changelog/src/template');

// Using built-in template
const changelog = await compileTemplate(releases, {
  template: 'compact'
});

// Using custom local template
const changelog = await compileTemplate(releases, {
  template: './my-template.hbs'
});

// Using remote template
const changelog = await compileTemplate(releases, {
  template: 'https://example.com/templates/custom.hbs'
});

// With custom Handlebars helpers
const changelog = await compileTemplate(releases, {
  template: 'compact',
  handlebarsSetup: './handlebars-helpers.js'
});
```
```

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

### Specify Latest Version Explicitly

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/configuration.md

Use `latestVersion` to define an explicit version string for the latest release. This creates a synthetic tag and is mutually exclusive with the `--package` option.

```bash
auto-changelog --latest-version 2.5.0

```

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

### Configure package.json version script

Source: https://github.com/cookpete/auto-changelog/blob/master/README.md

Add the auto-changelog command to the 'version' script in package.json to automatically update the changelog on version bumps. The -p flag uses the package.json version for the latest release.

```json
{
  "name": "my-awesome-package",
  "version": "1.0.0",
  "devDependencies": {
    "auto-changelog": "*"
  },
  "scripts": {
    "version": "auto-changelog -p && git add CHANGELOG.md"
  }
}
```

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

### Execute Shell Command with cmd

Source: https://github.com/cookpete/auto-changelog/blob/master/_autodocs/api-reference/utils.md

Executes a shell command and returns its stdout output as a string. It supports an optional progress callback to track bytes received. Note the limitations regarding command complexity and argument parsing.

```javascript
const { cmd } = require('auto-changelog/src/utils');

const tags = await cmd('git tag -l');
const log = await cmd('git log --oneline', (bytes) => {
  console.log(`Received ${bytes} bytes`);
});

// For complex commands, include full git command:
const commits = await cmd('git log HEAD --format=%H');
```