git

该插件会收集你的页面的 Git 信息，包括创建和更新时间、贡献者、变更历史记录等。

默认主题的 lastUpdated 和 contributors 就是由该插件支持的。

该插件主要用于开发主题，大部分情况下你不需要直接使用它。

使用方法

npm i -D @vuepress/plugin-git@next

.vuepress/config.ts
import { gitPlugin } from '@vuepress/plugin-git'

export default {
  plugins: [
    gitPlugin({
      // 配置项
    }),
  ],
}

Git 仓库

该插件要求你的项目在 Git 仓库下，这样它才能从提交历史记录中收集信息。

在构建站点时，你应该确保所有的提交记录是可以获取到的。举例来说， CI 工作流通常会在克隆你的仓库时添加 --depth 1 参数来避免拉取全部的提交记录，因此你需要禁用这个功能，以便该插件在 CI 可以中正常使用。

注意

该插件会显著降低准备数据的速度，特别是在你的页面数量很多的时候。你可以考虑在 dev 模式下禁用该插件来获取更好的开发体验。

配置项

createdTime

类型： boolean
默认值： true
详情：
是否收集页面的创建时间。

updatedTime

类型： boolean
默认值： true
详情：
是否收集页面的更新时间。

contributors

类型： boolean | ContributorsOptions

interface ContributorInfo {
  /**
   * 贡献者在 git 托管服务中的用户名
   */
  username: string
  /**
   * 贡献者显示在页面上的名字， 默认为 `username`
   */
  name?: string
  /**
   * 贡献者别名， 由于贡献者可能在本地 git 配置中保存的 用户名与 git 托管服务用户名不一致，
   * 这时候可以通过别名映射到真实的用户名
   */
  alias?: string[] | string
  /**
   * 贡献者在 Git 托管服务中的主邮箱
   */
  email?: string
  /**
   * 贡献者在 Git 托管服务中的备用邮箱，或者曾经使用过的邮箱
   */
  emailAlias?: string[] | string
  /**
   * 贡献者头像地址
   * 如果 git 托管服务为 `github`，则可以忽略不填，由插件自动填充
   */
  avatar?: string
  /**
   * 头像访问地址模式
   * - `:username` - 贡献者的用户名
   *
   * @example 'https://github.com/:username'
   */
  avatarPattern?: string
  /**
   * 贡献者访问地址
   * 如果 git 托管服务为 `github`，则可以忽略不填，由插件自动填充
   */
  url?: string
}

interface ContributorsOptions {
  /**
   * 贡献者信息
   */
  info?: ContributorInfo[]

  /**
   * 是否在贡献者信息中添加头像
   * @default false
   */
  avatar?: boolean

  /**
   * 贡献者转换函数，例如去重和排序
   * 该函数接收一个贡献者信息数组，返回一个新的贡献者信息数组。
   */
  transform?: (contributors: GitContributor[]) => GitContributor[]
}

默认值： true
详情：
是否收集页面的贡献者。

changelog

类型： boolean | ChangelogOptions

interface ChangelogOptions {
  /**
   * 最大变更记录条数
   */
  maxCount?: number

  /**
   * git 仓库的访问地址，例如：https://github.com/vuepress/ecosystem
   */
  repoUrl?: string

  /**
   * 提交记录访问地址模式
   * 默认值：':repo/commit/:hash'
   *
   * - `:repo` - git 仓库的访问地址
   * - `:hash` - 提交记录的 hash
   */
  commitUrlPattern?: string

  /**
   * issue 访问地址模式
   * 默认值：':repo/issues/:issue'
   *
   * - `:repo` - git 仓库的访问地址
   * - `:issue` - issue 的 id
   */
  issueUrlPattern?: string

  /**
   * tag 访问地址模式,
   * 默认值：':repo/releases/tag/:tag'
   *
   * - `:repo` - git 仓库的访问地址
   * - `:tag` - tag 的名称
   */
  tagUrlPattern?: string
}

默认值： false
详情：
是否收集页面变更历史记录。

filter

类型： (page: Page) => boolean
详情：
页面过滤器，如果返回 true ，该页面将收集 git 信息

locales

类型： Record<string, GitLocaleData>

export interface GitLocaleData {
  /**
   * 贡献者 标题
   */
  contributors: string
  /**
   * 更新日志 标题
   */
  changelog: string
  /**
   * 更新 `于` 文本
   */
  timeOn: string
  /**
   * 查看更新日志 文本
   */
  viewChangelog: string
  /**
   * 最近更新 文本
   */
  latestUpdateAt: string
}

详情：
多语言配置，在 Git 组件中使用。

Frontmatter

gitInclude

类型： string[]
详情：
文件相对路径组成的数组，该数组中的文件会在计算页面数据时被包含在内。
示例：

---
gitInclude:
  - relative/path/to/file1
  - relative/path/to/file2
---

contributors

类型: boolean | string[]
详情：
当前页面是否获取贡献者信息，该值会覆盖 contributors 配置项。
- true - 获取贡献者信息
- false - 不获取贡献者信息
- string[] - 额外的贡献者名单，有时候页面存在额外的贡献者，可以通过这个配置项来指定额外的贡献者名单来获取贡献者信息

changelog

类型： boolean
详情：
当前页面是否获取变更历史记录，该值会覆盖 changelog 配置项。

可组合式 API

你可以从 @vuepress/plugin-git/client 中导入以下可组合式 API。

useChangelog

获取当前页面的变更历史记录。

export interface GitChangelogItem {
  /**
   * Commit hash
   */
  hash: string
  /**
   * Unix timestamp in milliseconds
   */
  time: number
  /**
   * Commit message
   */
  message: string
  /**
   * The url of the commit
   */
  commitUrl?: string
  /**
   * release tag
   */
  tag?: string
  /**
   * The url of the release tag
   */
  tagUrl?: string
  /**
   * Commit author name
   */
  author: string
  /**
   * Commit author email
   */
  email: string

  /**
   * The co-authors of the commit
   */
  coAuthors?: CoAuthorInfo[]
  /**
   * Date text of the commit
   */
  date: string
}

export const useChangelog: (
  enabled?: MaybeRefOrGetter<boolean>,
) => ComputedRef<GitChangelogItem[]>

useContributors

获取当前页面的贡献者信息。

export interface GitContributorInfo {
  /**
   * Contributor display name
   */
  name: string
  /**
   * Contributor email
   */
  email: string

  /**
   * Contributor username on the git hosting service
   */
  username: string
  /**
   * Number of commits
   */
  commits: number
  /**
   * Contributor avatar
   */
  avatar?: string
  /**
   * The url of the contributor
   */
  url?: string
}

export const useContributors: (
  enabled?: MaybeRefOrGetter<boolean>,
) => ComputedRef<GitContributorInfo[]>

useLastUpdated

获取当前页面的最后更新时间。

export interface LastUpdated {
  /**
   * The date object of the last updated time
   */
  date: Date
  /**
   * The ISO string of the last updated time
   */
  iso: string
  /**
   * The formatted text of the last updated time
   */
  text: string
  /**
   * The locale of the last updated time
   */
  locale: string
}

export const useLastUpdated: (
  enabled?: MaybeRefOrGetter<boolean>,
) => ComputedRef<LastUpdated | null>

页面数据

该插件会向页面数据中添加一个 git 字段。

在使用该插件后，可以在页面数据中获取该插件收集到的 Git 信息：

import type { GitPluginPageData } from '@vuepress/plugin-git'
import { usePage } from 'vuepress/client'

export default {
  setup(): void {
    const page = usePage<GitPluginPageData>()
    console.log(page.value.git)
  },
}

git.createdTime

类型： number
详情：
页面第一次提交的 Unix 毫秒时间戳。
该属性将取当前页面及 gitInclude 中所列文件的第一次提交的时间戳的最小值。

git.updatedTime

类型： number
详情：
页面最后一次提交的 Unix 毫秒时间戳。
该属性将取当前页面及 gitInclude 中所列文件的最后一次提交的时间戳的最大值。

git.contributors

类型： GitContributor[]

interface GitContributor {
  // 在页面中显示的贡献者名称
  name: string
  email: string
  // 在 git 托管服务中的用户名
  username: string
  commits: number
  avatar?: string
  url?: string
}

详情：
页面的贡献者信息。
该属性将会包含 gitInclude 所列文件的贡献者。

git.changelog

类型： GitChangelog[]

interface GitChangelog {
  /**
   * 提交 hash
   */
  hash: string
  /**
   * Unix 时间戳，单位毫秒，提交时间
   */
  date: number
  /**
   * 提交信息
   */
  message: string
  /**
   * 提交者名称
   */
  author: string
  /**
   * 提交者邮箱
   */
  email: string
  /**
   * 提交访问地址
   */
  commitUrl?: string
  /**
   * tag 访问地址
   */
  tagUrl?: string
  /**
   * 协同作者列表
   */
  coAuthors?: {
    name: string
    email: string
  }[]
}

详情：
页面的变更历史记录。
该属性将会包含 gitInclude 所列文件的变更历史记录。

Git 组件

插件提供了与 Git 信息相关的全局组件，可以在主题中使用。

GitContributors

列出当前页面的贡献者信息。

<template>
  <div vp-content>
    <Content />
    <GitContributors />
  </div>
</template>

效果预览：

贡献者

Mister-Hope

meteorlxy

pengzhanbo

GitChangelog

列出当前页面的变更历史记录。

<template>
  <div vp-content>
    <Content />
    <GitChangelog />
  </div>
</template>

效果预览：

更新日志

2025/4/30 09:22

查看所有更新日志

8fc70-refactor: prefer useData and short api name (#448)于 2025/4/30
a13d5-docs: improve code block title于 2025/4/12
7dd53-feat(plugin-git): add support to find git contributor by email (#412)于 2025/3/27
d0d19-docs: use actual component for git preview于 2025/3/26
63eb8-feat(plugin-git): improve composables and add docs (#409)于 2025/3/23
acd14-feat(plugin-git): export global component, close #389 (#391)于 2025/3/6
56cec-feat(plugin-git): add built-in component <Contributors/> <Changelog/>, close #375 (#384)于 2025/3/4
ae96c-docs: add icons to docs (#332)于 2025/1/10
a0241-feat(plugin-git): improve commits parsing and optimize plugins (#292)于 2024/11/27
51b79-feat(plugin-git): improve performance and tweaks options (#287)于 2024/11/6
448d8-feat(plugin-git): add collect of co-authors (#285)于 2024/11/5
b526b-feat(plugin-git): support changelog and improve performance (#283)于 2024/11/3
d431d-feat(plugin-git): add transformContributors options于 2024/9/12
29ccd-chore: use eslint v9 (#237)于 2024/8/20
abd78-chore: update repo structure (#159)于 2024/5/29
082a9-feat(plugin-links-check): add links check plugin于 2024/2/21
ceb04-docs: add ecosystem docs (close #36) (#38)于 2024/1/30