facebook / facebook/docusaurus
π Windows: incorrect path conversion from Git POSIX paths (/x/...) to Windows paths (X:\...)
- 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
Assessment
This issue has not been assessed yet.