From 44e8ab0ed2c8e0304dc9d87d6c8202884619da4b Mon Sep 17 00:00:00 2001
From: Fourier <yang.fourier@gmail.com>
Date: Thu, 12 Mar 2026 16:37:01 +0800
Subject: [PATCH] docs: add MSYS/Git Bash path workaround

Closes #7
---
 README.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/README.md b/README.md
index 54bceb7..1747b41 100644
--- a/README.md
+++ b/README.md
@@ -180,6 +180,27 @@ notion auth status
 notion auth doctor
 ```
 
+## Troubleshooting
+
+### Windows: MSYS / Git Bash path mangling
+
+In MSYS-based shells (Git Bash, MSYS2), arguments starting with `/` are silently rewritten to Windows paths. This breaks API path arguments:
+
+```sh
+# ✗ /v1/users/me becomes C:/Program Files/Git/v1/users/me
+notion api GET /v1/users/me
+```
+
+**Fix:** disable MSYS path conversion:
+
+```sh
+MSYS_NO_PATHCONV=1 notion api GET /v1/users/me
+```
+
+Or export it for the session: `export MSYS_NO_PATHCONV=1`
+
+> This is a shell-level issue, not a bug in notion-cli. PowerShell and cmd.exe are not affected.
+
 ## Contributing
 
 Issues and PRs welcome at [github.com/4ier/notion-cli](https://github.com/4ier/notion-cli).