From e6e50054b05dc59c8b0830410f1080a48f2c270c Mon Sep 17 00:00:00 2001
From: Andrew Gallant <jamslam@gmail.com>
Date: Sun, 13 Sep 2020 09:29:28 -0400
Subject: doc: document cygwin path translation behavior

Kudos to @Pyker for posting more details about this.

Closes #1277
---
 CHANGELOG.md |  5 +++++
 FAQ.md       | 21 +++++++++++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2689a145..2e7abbcd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,11 @@ TBD
 ===
 Unreleased changes. Release notes have not yet been written.
 
+Bug fixes:
+
+* [BUG #1277](https://github.com/BurntSushi/ripgrep/issues/1277):
+  Document cygwin path translation behavior in the FAQ.
+
 
 12.1.1 (2020-05-29)
 ===================
diff --git a/FAQ.md b/FAQ.md
index 69c398d6..e27ecdcd 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -9,6 +9,7 @@
 * [How do I configure ripgrep's colors?](#colors)
 * [How do I enable true colors on Windows?](#truecolors-windows)
 * [How do I stop ripgrep from messing up colors when I kill it?](#stop-ripgrep)
+* [Why does using a leading `/` on Windows fail?](#because-cygwin)
 * [How can I get results in a consistent order?](#order)
 * [How do I search files that aren't UTF-8?](#encoding)
 * [How do I search compressed files?](#compressed)
@@ -315,6 +316,26 @@ available
 [here](https://github.com/BurntSushi/ripgrep/issues/281#issuecomment-269093893).
 
 
+<h3 name="because-cygwin">
+Why does using a leading `/` on Windows fail?
+</h3>
+
+If you're using cygwin on Windows and try to search for a pattern beginning
+with a `/`, then it's possible that cygwin is mangling that pattern without
+your knowledge. For example, if you tried running `rg /foo` in a cygwin shell
+on Windows, then cygwin might mistakenly perform path translation on `/foo`,
+which would result in `rg C:/msys64/foo` being searched instead.
+
+You can fix this in one of three ways:
+
+1. Stop using cygwin.
+2. Escape the leading slash with an additional slash. e.g., `rg //foo`.
+3. Temporarily disable path translation by setting `MSYS_NO_PATHCONV=1`. e.g.,
+   `MSYS_NO_PATHCONV=1 rg /foo`.
+
+For more details, see https://github.com/BurntSushi/ripgrep/issues/1277
+
+
 <h3 name="size-limit">
 How do I get around the regex size limit?
 </h3>
-- 
cgit v1.2.3