---
icon: la:git-alt
---
# git
This plugin collects Git information for your pages, including creation and update timestamps, contributor lists, and changelogs.
The [lastUpdated](../../themes/default/config.md#lastupdated) and [contributors](../../themes/default/config.md#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
```bash
npm i -D @vuepress/plugin-git@next
```
```ts title=".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](https://git-scm.com/book/en/Git-Basics-Getting-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](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt) 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
::: fields
@`createdTime` type=boolean default=`true`
Whether to collect the creation timestamp of the page.
@`updatedTime` type=boolean default=`true`
Whether to collect the update timestamp of the page.
@`contributors` type=`ContributorsOptions | boolean` default=`true`
Whether to collect contributor information for the page. You can also pass an object to configure it.
@@`contributors.info` type=`ContributorInfo[]`
Pre-defined contributor information.
@@@`contributors.info[*].username` type=string required
The contributor's username on the Git hosting service.
@@@`contributors.info[*].name` type=string
The contributor's display name on the page. Defaults to `username`.
@@@`contributors.info[*].alias` type=`string[] | 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[*].email` type=string
The primary email of the contributor.
@@@`contributors.info[*].emailAlias` type=`string[] | string`
Alternative emails for the contributor (e.g., emails used in past commits).
@@@`contributors.info[*].avatar` type=string
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[*].url` type=string
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.avatar` type=boolean default=`false`
Whether to include avatars in contributor information.
@@`contributors.avatarPattern` type=string
The pattern for avatar URLs.
- `:username` - Contributor's username
@@`contributors.transform` type=`(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.
@`changelog` type=`ChangelogOptions | boolean` default=`false`
Whether to collect the changelog for the page. You can also pass an object to configure it.
@@`changelog.maxCount` type=number
The maximum number of changelog entries to collect.
@@`changelog.repoUrl` type=string
The URL of the Git repository, e.g., `https://github.com/vuepress/ecosystem`.
@@`changelog.commitUrlPattern` type=string default=`':repo/commit/:hash'`
The pattern for commit URLs.
- `:repo` - The URL of the Git repository
- `:hash` - The hash of the commit
@@`changelog.issueUrlPattern` type=string default=`':repo/issues/:issue'`
The pattern for issue URLs.
- `:repo` - The URL of the Git repository
- `:issue` - The ID of the issue
@@`changelog.tagUrlPattern` type=string default=`':repo/releases/tag/:tag'`
The pattern for tag URLs.
- `:repo` - The URL of the Git repository
- `:tag` - The name of the tag
@`filter` type=`(page: Page) => boolean`
A function to filter pages. Git information will only be collected if this function returns `true`.
@`locales` type=`Record`
Locale configuration, primarily used by the [Git Components](#component).
See also: [Locales](../supported-locales.md).
@@`locales..contributors` type=string
The title for the contributors section.
@@`locales..changelog` type=string
The title for the changelog section.
@@`locales..timeOn` type=string
The text representing a commit "on" a specific date.
@@`locales..viewChangelog` type=string
The text for the "View Changelog" button.
@@`locales..latestUpdateAt` type=string
The text for "Latest Updated".
:::
## Frontmatter
::: fields
@`gitInclude` type=`string[]`
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).
```md
---
gitInclude:
- relative/path/to/file1
- relative/path/to/file2
---
```
@`contributors` type=`boolean | string[]`
Controls the collection of contributor information for the current page. This overrides the global [contributors](#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.
@`changelog` type=boolean
Whether to collect the changelog for the current page. This overrides the global [changelog](#changelog) option.
:::
## Composables
You can import the following composables from `@vuepress/plugin-git/client`.
### useChangelog
Returns the changelog for the current page.
```ts
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,
) => ComputedRef
```
### useContributors
Returns the list of contributors for the current page.
```ts
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,
) => ComputedRef
```
### useLastUpdated
Returns the last updated time of the current page.
```ts
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,
) => ComputedRef
```
## Page Data
This plugin injects a `git` field into the page data.
You can access the collected Git information via the page data object:
```ts
import type { GitPluginPageData } from '@vuepress/plugin-git'
import { usePage } from 'vuepress/client'
export default {
setup(): void {
const page = usePage()
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](#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](#gitinclude).
### git.contributors
- Type: `GitContributorInfo[]`
```ts
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](#gitinclude).
### git.changelog
- Type: `GitChangelogInfo[]`
```ts
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](#gitinclude).
## Git Component{#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.
```vue{4}
```
**Preview:**
### GitChangelog
Displays the changelog for the current page.
```vue{4}
```
**Preview:**