feat(plugin-git): support gitInclude frontmatter (close #449) (#460)

Co-authored-by: meteorlxy <meteor.lxy@foxmail.com>

docs/reference/default-theme/frontmatter.md

@@ -273,6 +273,7 @@ Frontmatter in this section will only take effect in normal pages.
 
 - Also see:
   - [Default Theme > Config > contributors](./config.md#contributors)
+
 ### sidebar
 
 - Type: `false | 'auto' | SidebarConfigArray | SidebarConfigObject`

docs/reference/plugin/git.md

@@ -68,6 +68,26 @@ This plugin will significantly slow down the speed of data preparation, especial
 
   Whether to collect page contributors or not.
 
+## Frontmatter
+
+### gitInclude
+
+- Type: `string[]`
+
+- Details:
+
+  An array of relative paths to be included when calculating page data.
+
+- Example:
+
+```md
+---
+gitInclude:
+  - relative/path/to/file1
+  - relative/path/to/file2
+---
+```
+
 ## Page Data
 
 This plugin will add a `git` field to page data.
@@ -94,6 +114,8 @@ export default {
 
   Unix timestamp in milliseconds of the first commit of the page.
 
+  This attribute would take the minimum of the first commit timestamps of the current page and the files listed in [gitInclude](#gitinclude).
+
 ### git.updatedTime
 
 - Type: `number`
@@ -102,6 +124,8 @@ export default {
 
   Unix timestamp in milliseconds of the last commit of the page.
 
+  This attribute would take the maximum of the last commit timestamps of the current page and the files listed in [gitInclude](#gitinclude).
+
 ### git.contributors
 
 - Type: `GitContributor[]`
@@ -117,3 +141,5 @@ interface GitContributor {
 - Details:
 
   The contributors information of the page.
+
+  This attribute would also include contributors to the files listed in [gitInclude](#gitinclude).

docs/zh/reference/plugin/git.md

@@ -68,6 +68,27 @@ module.exports = {
 
   是否收集页面的贡献者。
 
+
+## Frontmatter
+
+### gitInclude
+
+- 类型： `string[]`
+
+- 详情：
+
+  文件相对路径组成的数组，该数组中的文件会在计算页面数据时被包含在内。
+
+- 示例：
+
+```md
+---
+gitInclude:
+  - relative/path/to/file1
+  - relative/path/to/file2
+---
+```
+
 ## 页面数据
 
 该插件会向页面数据中添加一个 `git` 字段。
@@ -94,6 +115,8 @@ export default {
 
   页面第一次提交的 Unix 毫秒时间戳。
 
+  该属性将取当前页面及 [gitInclude](#gitinclude) 中所列文件的第一次提交的时间戳的最小值。
+
 ### git.updatedTime
 
 - 类型： `number`
@@ -102,6 +125,8 @@ export default {
 
   页面最后一次提交的 Unix 毫秒时间戳。
 
+  该属性将取当前页面及 [gitInclude](#gitinclude) 中所列文件的最后一次提交的时间戳的最大值。
+
 ### git.contributors
 
 - 类型： `GitContributor[]`
@@ -117,3 +142,5 @@ interface GitContributor {
 - 详情：
 
   页面的贡献者信息。
+
+  该属性将会包含 [gitInclude](#gitinclude) 所列文件的贡献者。

packages/@vuepress/plugin-git/package.json

@@ -29,6 +29,7 @@
   },
   "dependencies": {
     "@vuepress/core": "workspace:*",
+    "@vuepress/utils": "workspace:*",
     "execa": "^5.1.1"
   },
   "publishConfig": {

packages/@vuepress/plugin-git/src/node/gitPlugin.ts

@@ -1,5 +1,6 @@
 import type { Page, Plugin } from '@vuepress/core'
-import type { GitPluginPageData } from './types'
+import { path } from '@vuepress/utils'
+import type { GitPluginFrontmatter, GitPluginPageData } from './types'
 import {
   checkGitRepo,
   getContributors,
@@ -36,32 +37,32 @@ export const gitPlugin =
     return {
       name: '@vuepress/plugin-git',
 
-      extendsPage: async (page: Page<GitPluginPageData>) => {
+      extendsPage: async (
+        page: Page<GitPluginPageData, GitPluginFrontmatter>
+      ) => {
         page.data.git = {}
 
         if (!isGitRepoValid || page.filePathRelative === null) {
           return
         }
 
+        const filePaths = [
+          page.filePathRelative,
+          ...(page.frontmatter.gitInclude ?? []).map((item) =>
+            path.join(page.filePathRelative, '..', item)
+          ),
+        ]
+
         if (createdTime !== false) {
-          page.data.git.createdTime = await getCreatedTime(
-            page.filePathRelative,
-            cwd
-          )
+          page.data.git.createdTime = await getCreatedTime(filePaths, cwd)
         }
 
         if (updatedTime !== false) {
-          page.data.git.updatedTime = await getUpdatedTime(
-            page.filePathRelative,
-            cwd
-          )
+          page.data.git.updatedTime = await getUpdatedTime(filePaths, cwd)
         }
 
         if (contributors !== false) {
-          page.data.git.contributors = await getContributors(
-            page.filePathRelative,
-            cwd
-          )
+          page.data.git.contributors = await getContributors(filePaths, cwd)
         }
       },
     }

packages/@vuepress/plugin-git/src/node/types.ts

@@ -1,3 +1,7 @@
+export interface GitPluginFrontmatter {
+  gitInclude?: string[]
+}
+
 export interface GitPluginPageData {
   git: GitData
 }

packages/@vuepress/plugin-git/src/node/utils/getContributors.ts

@@ -2,12 +2,12 @@ import * as execa from 'execa'
 import type { GitContributor } from '../types'
 
 export const getContributors = async (
-  filePath: string,
+  filePaths: string[],
   cwd: string
 ): Promise<GitContributor[]> => {
   const { stdout } = await execa(
     'git',
-    ['--no-pager', 'shortlog', '-nes', 'HEAD', '--', filePath],
+    ['--no-pager', 'shortlog', '-nes', 'HEAD', '--', ...filePaths],
     {
       cwd,
       stdin: 'inherit',

packages/@vuepress/plugin-git/src/node/utils/getCreatedTime.ts

@@ -4,16 +4,19 @@ import * as execa from 'execa'
  * Get unix timestamp in milliseconds of the first commit
  */
 export const getCreatedTime = async (
-  filePath: string,
+  filePaths: string[],
   cwd: string
 ): Promise<number> => {
   const { stdout } = await execa(
     'git',
-    ['--no-pager', 'log', '--diff-filter=A', '--format=%at', filePath],
+    ['--no-pager', 'log', '--diff-filter=A', '--format=%at', ...filePaths],
     {
       cwd,
     }
   )
 
-  return Number.parseInt(stdout, 10) * 1000
+  return (
+    Math.min(...stdout.split('\n').map((item) => Number.parseInt(item, 10))) *
+    1000
+  )
 }

packages/@vuepress/plugin-git/src/node/utils/getUpdatedTime.ts

@@ -4,16 +4,26 @@ import * as execa from 'execa'
  * Get unix timestamp in milliseconds of the last commit
  */
 export const getUpdatedTime = async (
-  filePath: string,
+  filePaths: string[],
   cwd: string
 ): Promise<number> => {
   const { stdout } = await execa(
     'git',
-    ['--no-pager', 'log', '-1', '--format=%at', filePath],
+    [
+      '--no-pager',
+      'log',
+      '--format=%at',
+      // if there is only one file to be included, add `-1` option
+      ...(filePaths.length > 1 ? [] : ['-1']),
+      ...filePaths,
+    ],
     {
       cwd,
     }
   )
 
-  return Number.parseInt(stdout, 10) * 1000
+  return (
+    Math.max(...stdout.split('\n').map((item) => Number.parseInt(item, 10))) *
+    1000
+  )
 }

packages/@vuepress/plugin-git/tsconfig.build.json

@@ -6,5 +6,8 @@
     "outDir": "./lib"
   },
   "include": ["./src"],
-  "references": [{ "path": "../core/tsconfig.build.json" }]
+  "references": [
+    { "path": "../core/tsconfig.build.json" },
+    { "path": "../utils/tsconfig.build.json" }
+  ]
 }