fix(plugin-git): support submodule by mtfhx · Pull Request #621 · vuepress/ecosystem

mtfhx · 2026-03-02T08:49:03Z

Before submitting the PR, please make sure you do the following

Read the Contributing Guidelines.
Provide a description in this PR that addresses what the PR is solving. If this PR is going to solve an existing issue, please reference the issue (e.g. close #123).

What is the purpose of this pull request?

Bug fix
New feature
Other

Description

When VuePress is built from a subdirectory or within a monorepo, plugin-git may fail to locate files correctly.

In my case, the documentation content of the site is maintained in an independent private repository and linked via Git submodules (the site itself is public, but the content repository is private). In this setup, the Git plugin is unable to correctly retrieve commit metadata such as author and date.

This PR improves the behavior with the following workflow:
1. Detect the Git repository root using: git rev-parse --show-toplevel
2. Resolve the target file path:
• Convert to absolute path first
• Then transform it into a path relative to the detected repository root
3. Execute git log from the repository root directory instead of the current working directory

Screenshots

Before

After

- add helper to detect git repository root via `git rev-parse --show-toplevel` - normalize/resolve target file path to repo-relative before calling `git log` - run `git log` from repository root fallback to current cwd w

Mister-Hope

The Git plugin is slow enough. I believe a directory cache can be stored here. A directory shall be resolved only once.

e.g.: /path/a.md triggers a check for the /path/ directory, and /path/b.md shall reuse the result from the cache later

Since extendsPage hooks are async, you may need to handle promises here in case the commands are still executed several times due to the delayed return of the first one.

Adding extra memory here shall be worthy for a cache, and the cache map shall be cleared in the onPrepared stage (to save build memory usage), as at this moment we can no longer add pages.

Copilot

Pull request overview

Fixes @vuepress/plugin-git commit collection when VuePress runs from a subdirectory / monorepo setup by ensuring git commands run from the actual repository root and file paths are resolved relative to that root.

Changes:

Add a helper to detect the git repository root via git rev-parse --show-toplevel.
Convert the target file path to repo-relative form and run git log from the detected repo root.

Copilot · 2026-03-02T09:20:26Z

  const format = getGitLogFormat(options)
+  const gitRoot = await getGitRepoRoot(filepath, cwd)



getGitRepoRoot() is executed for every file in getRawCommits(), which adds an extra git spawn per file and can noticeably slow down builds on large sites (especially since getCommits() runs for every page). Consider memoizing repo roots by directory (e.g. a Map keyed by dir/cwd) or computing the repo root once per getCommits() call and reusing it for all filepaths.

Copilot · 2026-03-02T09:20:27Z

+      if (code === 0) {
+        resolve(path.normalize(stdoutData.trim()))
+      } else {
+        logger.error(


getGitRepoRoot() logs an error for any non-zero git rev-parse exit, but git rev-parse --show-toplevel can fail in expected situations (e.g. included files outside the repo / wrong directory). Logging at error level here can create noisy, duplicated output (this function then returns null and git log may fail and be logged again). Consider treating common non-repo failures as a non-error (return null silently or at debug level) and only surface an error once with full context when commit collection ultimately fails.

Suggested change

logger.error(

logger.debug(

Mister-Hope · 2026-03-02T11:34:33Z

It seems that copilot shares the same view with me.

A cache is necessary

Mister-Hope · 2026-03-03T11:51:02Z

Thanks for the update, will review this later.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

Copilot · 2026-03-08T09:02:22Z

  const format = getGitLogFormat(options)
+  const gitRoot = await getGitRepoRoot(filepath, cwd)

  try {
+    let repoRelativeFilePath = filepath
+    if (gitRoot) {
+      // Resolve to absolute path first, then convert to repo-relative path
+      const absFilePath = path.isAbsolute(repoRelativeFilePath)
+        ? repoRelativeFilePath
+        : path.resolve(cwd, repoRelativeFilePath)
+
+      repoRelativeFilePath = path.relative(gitRoot, absFilePath)
+    } else {
+      logger.warn(
+        `Failed to resolve git repo root for "${filepath}" under cwd "${cwd}", falling back to cwd; git history may be incomplete.`,
+      )
+    }
+
    const stdout = await runGitLog(
      [
        '--max-count=-1',
        `--format=${format}${COMMIT_SPLITTER}`,
        '--date=unix',
        '--follow',
        '--',
-        filepath,
+        repoRelativeFilePath,
      ],
-      cwd,
+      gitRoot || cwd,


getCommits() can now fetch commit histories from different git roots within a single call (because getGitRepoRoot() is computed per filepath). However, mergeRawCommits() still merges commits solely by hash, which assumes all commits come from the same repository. If filepaths ever span multiple repos (e.g. via gitInclude pointing outside a submodule), identical hashes across repos could be merged incorrectly. Consider either enforcing that all filepaths resolve to the same gitRoot (and warn/skip otherwise), or include the repo identity (e.g. gitRoot) in the merge key / raw commit data so merges remain correct across repos.

Copilot · 2026-03-08T09:02:22Z

+  if (cachedResult !== undefined || gitRepoRootResultCache.has(dir))
+    return Promise.resolve(cachedResult ?? null)


The cache hit check is overly complex: gitRepoRootResultCache stores only string | null, so get(dir) returning undefined already means “not cached”. The extra || gitRepoRootResultCache.has(dir) branch is redundant and makes it harder to reason about caching null vs “missing”. Consider rewriting this to a single has(dir) check (or a single cachedResult !== undefined check) for clarity.

Suggested change

if (cachedResult !== undefined || gitRepoRootResultCache.has(dir))

return Promise.resolve(cachedResult ?? null)

if (cachedResult !== undefined) return Promise.resolve(cachedResult)

Copilot · 2026-03-08T09:02:23Z

+        logger.error(
+          `git rev-parse failed (code=${code}): ${stderrData.trim()}`,
+        )
+        resolve(null)


When git rev-parse --show-toplevel fails, the error log currently doesn’t include which directory it was executed in. Including dir (or the original filePath) in the logged message would make it much easier to diagnose submodule / monorepo edge cases, especially since failures may be intermittent depending on which file is being processed.

Mister-Hope

I am not sure how the logger.error will be triggered, can you plz provide some examples? Could it be too noisy in some cases?

Mister-Hope · 2026-03-11T08:47:37Z

@pengzhanbo Please review it.

I think the changelog might be broken after this is merged with submodules, but previously it will be broken too.

We might need another PR to fix that.

pengzhanbo · 2026-03-17T13:10:12Z

The related Vue component of the plugin renders a link pointing to the repository's commit URL, which consists of the repository address + hash. If the file belongs to a sub-repository, this commit record will lead to an incorrect main repository commit link.

mtfhx · 2026-03-18T07:47:38Z

I am not sure how the logger.error will be triggered, can you plz provide some examples? Could it be too noisy in some cases?

During the document compilation process, the version repository was corrupted (deleting the .git directory during compilation can generate logs). Of course, this is an extreme case, and there might also be noise. If necessary, I can delete this part of the log and keep only the error-handling section.

Mister-Hope · 2026-04-01T07:05:06Z

Can you try to fix changelog in the same PR?

mtfhx · 2026-05-13T07:47:18Z

I’ve tried to fix the link issue. @Mister-Hope @pengzhanbo

Please review it when convenient. Thanks!

Mister-Hope · 2026-05-14T06:08:38Z

Appreciated, I am not an expert at Git, so let me review it carefully across different agents with their explanations about these commands.

Mister-Hope · 2026-05-14T06:13:20Z

@pengzhanbo Local security check suggests git plugin is now dangerous as filePath are passed to command args without validating.

It would be dangerous if the filePath is rewritten to something like a.md && cat /etc/passwd or a.md && rm -rf /. in functions like getGitCreateDate.

Could you check this part once this PR is merged? I will currently leave these security issue here.

mtfhx added 2 commits February 24, 2026 17:48

fix(plugin-git): stabilize getGitRepoRoot path resolution

ee60c9e

Mister-Hope reviewed Mar 2, 2026

View reviewed changes

Comment thread plugins/development/plugin-git/src/node/utils/getCommits.ts Outdated

Mister-Hope requested changes Mar 2, 2026

View reviewed changes

Mister-Hope requested a review from Copilot March 2, 2026 09:15

Copilot started reviewing on behalf of Mister-Hope March 2, 2026 09:16 View session

mtfhx changed the title ~~Plugin git~~ Plugin git support submodule Mar 2, 2026

Merge branch 'main' into plugin-git

79d56fb

Copilot AI reviewed Mar 2, 2026

View reviewed changes

mtfhx added 2 commits March 2, 2026 17:48

perf(plugin-git): improve fallback warning

eeafcb8

refactor(plugin-git): refining the variable name

aaa7746

perf(plugin-git): cache git repo root lookups and clear cache onPrepared

bc24cb1

mtfhx changed the title ~~Plugin git support submodule~~ fix(plugin-git): support submodule Mar 3, 2026

Mister-Hope requested a review from Copilot March 8, 2026 08:57

Copilot started reviewing on behalf of Mister-Hope March 8, 2026 08:57 View session

Copilot AI reviewed Mar 8, 2026

View reviewed changes

Mister-Hope reviewed Mar 8, 2026

View reviewed changes

Mister-Hope added 2 commits March 8, 2026 17:33

Merge branch 'main' into plugin-git

e3f22c1

Merge branch 'main' into plugin-git

59f88e1

Mister-Hope previously approved these changes Mar 10, 2026

View reviewed changes

Merge branch 'main' into plugin-git

19afa26

Mister-Hope requested a review from pengzhanbo March 11, 2026 08:46

Merge branch 'main' into plugin-git

366a4f5

Merge branch 'main' into plugin-git

0fa382d

mtfhx and others added 4 commits April 9, 2026 15:52

Merge branch 'main' into plugin-git

b8fbd36

Merge branch 'main' into plugin-git

12d2d17

Merge branch 'main' into plugin-git

affa47c

fix: try to fix commit link

52e6a36

mtfhx dismissed Mister-Hope’s stale review via 52e6a36 May 13, 2026 07:21

Merge branch 'main' into plugin-git

80fc507

		const format = getGitLogFormat(options)
		const gitRoot = await getGitRepoRoot(filepath, cwd)

		if (cachedResult !== undefined \|\| gitRepoRootResultCache.has(dir))
		return Promise.resolve(cachedResult ?? null)

	if (cachedResult !== undefined \|\| gitRepoRootResultCache.has(dir))
	return Promise.resolve(cachedResult ?? null)
	if (cachedResult !== undefined) return Promise.resolve(cachedResult)

Conversation

mtfhx commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Before submitting the PR, please make sure you do the following

What is the purpose of this pull request?

Description

Screenshots

Uh oh!

Uh oh!

Mister-Hope left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Mister-Hope commented Mar 2, 2026

Uh oh!

Mister-Hope commented Mar 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Mister-Hope left a comment

Choose a reason for hiding this comment

Uh oh!

Mister-Hope commented Mar 11, 2026

Uh oh!

pengzhanbo commented Mar 17, 2026

Uh oh!

mtfhx commented Mar 18, 2026

Uh oh!

Mister-Hope commented Apr 1, 2026

Uh oh!

mtfhx commented May 13, 2026

Uh oh!

Mister-Hope commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Mister-Hope commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mtfhx commented Mar 2, 2026 •

edited

Loading

Mister-Hope left a comment •

edited

Loading

Mister-Hope commented May 14, 2026 •

edited

Loading

Mister-Hope commented May 14, 2026 •

edited

Loading