git

@vuepress/plugin-git

This plugin collects Git information for your pages, including creation and update timestamps, contributor lists, and changelogs.

The lastUpdated and contributors features in the default theme are powered by this plugin.

This plugin is primarily intended for theme development. In most cases, you will not need to use it directly.

Usage

npm i -D @vuepress/plugin-git@next
.vuepress/config.ts
import { gitPlugin } from '@vuepress/plugin-git'

export default {
  plugins: [
    gitPlugin({
      // options
    }),
  ],
}

Git Repository

This plugin requires your project to be located within a Git Repository to properly collect data from the commit history.

Ensure that the full commit history is available when building your site. CI workflows often use --depth 1 when cloning repositories to improve performance, which prevents the plugin from accessing the necessary history. You must disable this shallow clone behavior (usually by setting fetch-depth: 0) for the plugin to work correctly in CI environments.

Warning

This plugin may significantly increase data preparation time during builds, especially for projects with a large number of pages. You may consider disabling this plugin in dev mode to improve the development experience.

Options

createdTimeboolean
Defaulttrue

Whether to collect the creation timestamp of the page.

updatedTimeboolean
Defaulttrue

Whether to collect the update timestamp of the page.

contributorsContributorsOptions | boolean
Defaulttrue

Whether to collect contributor information for the page. You can also pass an object to configure it.

contributors.infoContributorInfo[]

Pre-defined contributor information.

contributors.info[*].usernameRequiredstring

The contributor's username on the Git hosting service.

contributors.info[*].namestring

The contributor's display name on the page. Defaults to username.

contributors.info[*].aliasstring[] | string

Aliases for the contributor. Useful when a contributor's local Git username differs from their hosting service username. Use aliases to map them to the correct account.

contributors.info[*].emailstring

The primary email of the contributor.

contributors.info[*].emailAliasstring[] | string

Alternative emails for the contributor (e.g., emails used in past commits).

contributors.info[*].avatarstring

The avatar URL of the contributor. If the hosting service is github, this can be left blank, as the plugin will automatically populate it.

contributors.info[*].urlstring

The profile URL of the contributor. If the hosting service is github, this can be left blank, as the plugin will automatically populate it.

contributors.avatarboolean
Defaultfalse

Whether to include avatars in contributor information.

contributors.avatarPatternstring

The pattern for avatar URLs.

  • :username - Contributor's username
contributors.transform(contributors: GitContributorInfo[]) => GitContributorInfo[]

A function to transform the contributors list (e.g., to deduplicate or sort). Accepts the list collected by the plugin and returns the transformed list.

changelogChangelogOptions | boolean
Defaultfalse

Whether to collect the changelog for the page. You can also pass an object to configure it.

changelog.maxCountnumber

The maximum number of changelog entries to collect.

changelog.repoUrlstring

The URL of the Git repository, e.g., https://github.com/vuepress/ecosystem.

changelog.commitUrlPatternstring
Default':repo/commit/:hash'

The pattern for commit URLs.

  • :repo - The URL of the Git repository
  • :hash - The hash of the commit
changelog.issueUrlPatternstring
Default':repo/issues/:issue'

The pattern for issue URLs.

  • :repo - The URL of the Git repository
  • :issue - The ID of the issue
changelog.tagUrlPatternstring
Default':repo/releases/tag/:tag'

The pattern for tag URLs.

  • :repo - The URL of the Git repository
  • :tag - The name of the tag
filter(page: Page) => boolean

A function to filter pages. Git information will only be collected if this function returns true.

localesRecord<string, GitLocaleData>

Locale configuration, primarily used by the Git Components.

See also: Locales.

locales.<localePath>.contributorsstring

The title for the contributors section.

locales.<localePath>.changelogstring

The title for the changelog section.

locales.<localePath>.timeOnstring

The text representing a commit "on" a specific date.

locales.<localePath>.viewChangelogstring

The text for the "View Changelog" button.

locales.<localePath>.latestUpdateAtstring

The text for "Latest Updated".

Frontmatter

gitIncludestring[]

An array of relative file paths. The Git history of these files will be included when calculating the current page's data (e.g., timestamps and contributors).

---
gitInclude:
  - relative/path/to/file1
  - relative/path/to/file2
---
contributorsboolean | string[]

Controls the collection of contributor information for the current page. This overrides the global contributors option.

  • true - Enable collection.
  • false - Disable collection.
  • string[] - A list of additional contributors. Useful for manually specifying contributors who may not appear in the Git history.
changelogboolean

Whether to collect the changelog for the current page. This overrides the global changelog option.

Composables

You can import the following composables from @vuepress/plugin-git/client.

useChangelog

Returns the changelog for the current page.

export interface CoAuthorInfo {
  /**
   * Co-author name
   */
  name: string
  /**
   * Co-author email
   */
  email: string
}

export interface GitChangelogItem extends GitChangelogInfo {
  /**
   * Commit hash
   */
  hash: string
  /**
   * Unix timestamp in milliseconds
   */
  time: number
  /**
   * Commit message
   */
  message: string
  /**
   * The URL of the commit
   */
  commitUrl?: string
  /**
   * Release tag associated with the commit
   */
  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[]

  /**
   * Formatted date string of the commit
   */
  date: string
}

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

useContributors

Returns the list of contributors for the current page.

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 URL
   */
  avatar?: string
  /**
   * Contributor profile URL
   */
  url?: string
}

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

useLastUpdated

Returns the last updated time of the current page.

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 string for the date format
   */
  locale: string
}

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

Page Data

This plugin injects a git field into the page data.

You can access the collected Git information via the page data object:

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

  • Type: number

  • Details:

    The Unix timestamp (in milliseconds) of the page's first commit.

    This value reflects the earliest commit timestamp among the current page and any files listed in gitInclude.

git.updatedTime

  • Type: number

  • Details:

    The Unix timestamp (in milliseconds) of the page's last commit.

    This value reflects the latest commit timestamp among the current page and any files listed in gitInclude.

git.contributors

  • Type: GitContributorInfo[]
interface GitContributorInfo {
  // display name
  name: string
  email: string
  // username on the git hosting service
  username: string
  commits: number
  avatar?: string
  url?: string
}

  • Details:

    The list of contributors for the page.

    This list includes contributors from the current page and any files listed in gitInclude.

git.changelog

  • Type: GitChangelogInfo[]
interface CoAuthorInfo {
  /**
   * Co-author name
   */
  name: string
  /**
   * Co-author email
   */
  email: string
}

interface GitChangelogInfo {
  /**
   * Commit hash
   */
  hash: string
  /**
   * Unix timestamp in milliseconds
   */
  time: number
  /**
   * Commit message
   */
  message: string
  /**
   * The URL of the commit
   */
  commitUrl?: string
  /**
   * Release tag associated with the commit
   */
  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[]
}

  • Details:

    The changelog for the page.

    This list includes commit history from the current page and any files listed in gitInclude.

Git Component

The plugin registers global components for displaying Git information, which can be easily used within themes.

GitContributors

Displays a list of contributors for the current page.

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

Preview:

Contributors

Mister-Hopemeteorlxypengzhanbo

GitChangelog

Displays the changelog for the current page.

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

Preview:

Changelog

9/28/26, 4:40 AM
View All Changelog
  • d715a-docs: rebuild docs (#925)on
  • 2c88a-docs: improve git docson
  • 81918-build: bump deps (#546)on
  • 0f128-refactor(plugin-git): add jsdoc and improve docs (#493)on
  • 8fc70-refactor: prefer useData and short api name (#448)on
  • a13d5-docs: improve code block titleon
  • 7dd53-feat(plugin-git): add support to find git contributor by email (#412)on
  • d0d19-docs: use actual component for git previewon
  • 63eb8-feat(plugin-git): improve composables and add docs (#409)on
  • acd14-feat(plugin-git): export global component, close #389 (#391)on
  • 56cec-feat(plugin-git): add built-in component <Contributors/> <Changelog/>, close #375 (#384)on
  • ae96c-docs: add icons to docs (#332)on
  • a0241-feat(plugin-git): improve commits parsing and optimize plugins (#292)on
  • 51b79-feat(plugin-git): improve performance and tweaks options (#287)on
  • 448d8-feat(plugin-git): add collect of co-authors (#285)on
  • b526b-feat(plugin-git): support changelog and improve performance (#283)on
  • d431d-feat(plugin-git): add transformContributors optionson
  • 29ccd-chore: use eslint v9 (#237)on
  • abd78-chore: update repo structure (#159)on
  • 082a9-feat(plugin-links-check): add links check pluginon
  • ceb04-docs: add ecosystem docs (close #36) (#38)on