---
title: "CommitChangelog"
description: "CommitChangelog automatically fetches the Git commit history of a specific component or file from a GitHub repository and displays it as timeline cards. It supports filtering by filename, path, and author, as well as path inference via commitPath, suffix, and casing. Requires the NUXT_GITHUB_TOKEN environment variable."
canonical_url: "https://docs.mhaibaraai.cn/en/docs/components/commit-changelog"
---
# CommitChangelog

> CommitChangelog automatically fetches the Git commit history of a specific component or file from a GitHub repository and displays it as timeline cards. It supports filtering by filename, path, and author, as well as path inference via commitPath, suffix, and casing. Requires the NUXT_GITHUB_TOKEN environment variable.

## Overview

Fetches the commit history of a specified file path from a GitHub repository and displays it as a timeline.

## Prerequisites

- **GitHub configuration**: configure your GitHub information in `app/app.config.ts`. See [GitHub integration configuration](https://docs.mhaibaraai.cn/en/docs/getting-started/configuration#github-integration) for details.
- **Environment variable**: configure your GitHub Token in the `.env` file:
```bash
NUXT_GITHUB_TOKEN=ghp_your_personal_access_token_here
```

> [!WARNING]
> See: https://github.com/settings/tokens
> 
> The GitHub Token needs permission to read the repository's commit history (the 
> 
> repo
> 
>  or 
> 
> public_repo
> 
>  scope). You can create a new token in GitHub Settings > Developer settings > Personal access tokens.

> [!TIP]
> 
> If 
> 
> NUXT_GITHUB_TOKEN
> 
>  is not configured, the component will not error; instead it displays "No recent changes".

## Usage

### Basic usage

Use the following syntax in your Markdown documentation:

```md [md]
:commit-changelog
```

The component automatically infers the component name from the current page route and fetches the commit history of the corresponding file.

### Displaying a Vue component's commit history

```md [md]
:commit-changelog{name="Accordion"}
```

Example output:

- [`a1b2c`](https://github.com/.../commit/a1b2c3) — fix: resolve the collapse animation delay [#45](https://github.com/.../issues/45)
- [`d4e5f`](https://github.com/.../commit/d4e5f6) — feat: add `disabled` prop support

### Displaying a TypeScript file's commit history

```md [md]
:commit-changelog{suffix="ts" name="useColorMode"}
```

### Filtering commits by author

Add `author` to the URL query parameters to show only a specific author's commits:

```md [md]
:commit-changelog{author="user@example.com"}
```

> [!TIP]
> 
> The 
> 
> author
> 
>  parameter can be a GitHub username or email address. For example: 
> 
> ?author=octocat
> 
>  or 
> 
> ?author=user@example.com

### Files named in kebab-case

For `composables` or `utils` files named in `kebab-case`:

```md [md]
:commit-changelog{suffix="ts" name="use-user" casing="kebab" commitPath="composables"}
```

This looks for the commit history of `composables/use-user.ts`.

> [!TIP]
> 
> If the files in your project are consistently named in `kebab-case`, it is recommended to configure `github.casing: 'kebab'` globally in `app/app.config.ts` so you do not need to repeat it for every component.
> 
> ```ts [app/app.config.ts]
> export default defineAppConfig({
>   github: {
>     casing: 'kebab', // Use kebab-case as the global default
>     // Other configuration...
>   }
> })
> ```

### Associating multiple files

A single doc page often maps to several source files (for example, a group of related composables). The `files` array lets you associate multiple files at once; the component merges their commit histories, deduplicates them, and displays them in a single timeline ordered newest-first.

Each entry in `files` is a **partial override** of the top-level configuration (`commitPath`, `prefix`, `suffix`, `name`, `casing`); unspecified fields fall back to the top-level values. So put the common parts (same directory, same extension) at the top level and only specify the differing fields inside `files`:

```md [md]
::commit-changelog
---
commitPath: 'layer/app/composables'
suffix: 'ts'
files:
  - name: 'useHeader'
  - name: 'useNavigation'
---
```

### Full configuration example

```md [md]
::commit-changelog
---
commitPath: 'packages/core/src'
prefix: 'components'
suffix: 'ts'
name: 'useUser'
author: 'user@example.com'
---
```

## API

### Props

```ts
/**
 * Props for the CommitChangelog component
 */
interface CommitChangelogProps {
  /**
   * 仓库中的文件路径
   */
  commitPath?: string | undefined;
  /**
   * 文件路径的前缀
   */
  prefix?: string | undefined;
  /**
   * 文件扩展名
   */
  suffix?: string | undefined;
  /**
   * 要获取更新日志的组件或文件名
   */
  name?: string | undefined;
  /**
   * 按作者筛选提交
   */
  author?: string | undefined;
  /**
   * 文件名的命名格式
   * - 'auto': Vue 文件使用 PascalCase，其他使用 camelCase（默认）
   * - 'kebab': 保持 kebab-case（如 use-user.ts）
   * - 'camel': 转换为 camelCase（如 useUser.ts）
   * - 'pascal': 转换为 PascalCase（如 UseUser.ts）
   */
  casing?: CommitCasing | undefined;
  /**
   * 关联多个文件：每一项与顶层 props 合并后各自解析出一个文件路径，
   * 对应的提交记录会合并去重并按时间倒序展示
   */
  files?: CommitChangelogFile[] | undefined;
}
```

## Related

- [PageLastCommit](https://docs.mhaibaraai.cn/en/docs/components/page-last-commit) — display the last update info for the current page
- [useFetchComponentMeta](https://docs.mhaibaraai.cn/en/docs/composables/fetch-component-meta) — the composable for fetching component metadata

## Changelog

See commit history for [layer/app/components/content/CommitChangelog.vue](https://github.com/mhaibaraai/movk-nuxt-docs/commits/main/layer/app/components/content/CommitChangelog.vue).

---

- [GitHub](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/components/content/CommitChangelog.vue)


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.