facebook / facebook/docusaurus

πŸ› Windows: incorrect path conversion from Git POSIX paths (/x/...) to Windows paths (X:\...)

Open
#11,920 9 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
TypeScript
Stars
66.2k
Forks
10k
Avg merge
1d 3h
Merged PRs (30d)
52

Description

## πŸ› Windows: incorrect path conversion from Git POSIX paths (`/x/...`) to Windows paths (`X:\...`)

### πŸ“ Summary

Since upgrading to Docusaurus 3 (tested on 3.10.0), builds fail on Windows due to incorrect conversion of Git POSIX-style paths (e.g. `/p/...`) into invalid Windows paths (`P:\p\...`).

This appears to be introduced by the new `vcsGitEager` logic.

---

### βœ… Expected behavior

Git may return paths like:

```
/p/projets/my-repo
```

These should be correctly converted to:

```
P:\projets\my-repo
```

---

### ❌ Actual behavior

Docusaurus converts:

```
/p/projets/my-repo
```

into:

```
P:\p\projets\my-repo
```

This leads to:

```
ENOENT: no such file or directory, realpath 'P:\p\projets\my-repo'
```

---

### πŸ” Steps to reproduce

1. Use Windows
2. Use Git Bash / MSYS environment (Git returns `/x/...` paths)
3. Run:

```
docusaurus build
```

---

### πŸ“¦ Environment

* Docusaurus: 3.10.0
* Node.js: 20.x
* OS: Windows
* Shell: Git Bash (MSYS)

---

### πŸ”Ž Root cause analysis

Git (via MSYS) returns POSIX-style paths:

```
/p/projets/...
```

Docusaurus attempts to normalize these paths but does not correctly handle MSYS mount-style paths (`/c/`, `/d/`, `/p/`, etc.).

The conversion logic seems to incorrectly prepend the drive letter **without removing the mount prefix**, resulting in duplicated segments (`P:\p\...`).

---

### πŸ’‘ Suggested fix

Detect MSYS-style paths and normalize them properly:

```js
function normalizeWindowsPath(p) {
const match = p.match(/^\/([a-z])\/(.*)/i);
if (match) {
return `${match[1].toUpperCase()}:\\${match[2].replace(/\//g, '\\')}`;
}
return p;
}
```

---

### πŸ§ͺ Additional notes

* `git rev-parse --show-toplevel` returns `/p/...` (expected in Git Bash)
* `fs.realpathSync('.')` returns correct Windows path (`P:\...`)
* Issue only occurs inside Docusaurus Git processing
* Did not occur before Docusaurus 3 (likely due to new eager Git logic)

---

### πŸš€ Impact

* Breaks builds on Windows when using Git Bash / MSYS
* Affects local development environments
* Blocks upgrade to Docusaurus 3 for affected setups

---

### πŸ™ Thanks

Happy to test a fix or provide additional debug logs if needed!

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.