From b8e6d50bbe9c2cfa9fd661e5090d2b1fa27c3429 Mon Sep 17 00:00:00 2001
From: Andrew Gallant <jamslam@gmail.com>
Date: Mon, 12 Feb 2018 17:54:12 -0500
Subject: [PATCH] doc: add "grep replacement" question to FAQ

I am tired of being throwing "but ripgrep is marketed as a grep
replacement" in my face. Let's answer it once and for all.
---
 FAQ.md    | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md |  6 +++---
 2 files changed, 67 insertions(+), 3 deletions(-)

diff --git a/FAQ.md b/FAQ.md
index 184b401c..b7facfe3 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -20,6 +20,7 @@
 * [How do I create an alias for ripgrep on Windows?](#rg-alias-windows)
 * [How do I create a PowerShell profile?](#powershell-profile)
 * [How do I pipe non-ASCII content to ripgrep on Windows?](#pipe-non-ascii-windows)
+* [Can ripgrep replace grep?](#posix4ever)
 
 
 <h3 name="config">
@@ -466,3 +467,66 @@ that the console will use for printing to UTF-8 with
 `[System.Console]::OutputEncoding = [System.Text.Encoding]::UTF8`. This
 will also reset when PowerShell is restarted, so you can add that line
 to your profile as well if you want to make the setting permanent.
+
+
+<h3 name="posix4ever">
+Can ripgrep replace grep?
+</h3>
+
+Yes and no.
+
+If, upon hearing that "ripgrep can replace grep," you *actually* hear, "ripgrep
+can be used in every instance grep can be used, in exactly the same way, for
+the same use cases, with exactly the same bug-for-bug behavior," then no,
+ripgrep trivially *cannot* replace grep. Moreover, ripgrep will *never* replace
+grep.
+
+If, upon hearing that "ripgrep can replace grep," you *actually* hear, "ripgrep
+can replace grep in some cases and not in other use cases," then yes, that is
+indeed true!
+
+Let's go over some of those use cases in favor of ripgrep. Some of these may
+not apply to you. That's OK. There may be other use cases not listed here that
+do apply to you. That's OK too.
+
+(For all claims related to performance in the following words, see my
+[blog post](https://blog.burntsushi.net/ripgrep/)
+introducing ripgrep.)
+
+* Are you frequently searching a repository of code? If so, ripgrep might be a
+  good choice since there's likely a good chunk of your repository that you
+  don't want to search. grep, can, of course, be made to filter files using
+  recursive search, and if you don't mind writing out the requisite `--exclude`
+  rules or writing wrapper scripts, then grep might be sufficient. (I'm not
+  kidding, I myself did this with grep for almost a decade before writing
+  ripgrep.) But if you instead enjoy having a search tool respect your
+  `.gitignore`, then ripgrep might be perfect for you!
+* Are you frequently searching non-ASCII text that is UTF-8 encoded? One of
+  ripgrep's key features is that it can handle Unicode features in your
+  patterns in a way that tends to be faster than GNU grep. Unicode features
+  in ripgrep are enabled by default; there is no need to configure your locale
+  settings to use ripgrep properly because ripgrep doesn't respect your locale
+  settings.
+* Do you need to search UTF-16 files and you don't want to bother explicitly
+  transcoding them? Great. ripgrep does this for you automatically. No need
+  to enable it.
+* Do you need to search a large directory of large files? ripgrep uses
+  parallelism by default, which tends to make it faster than a standard
+  `grep -r` search. However, if you're OK writing the occasional
+  `find ./ -print0 | xargs -P8 -0 grep` command, then maybe grep is good
+  enough.
+
+Here are some cases where you might *not* want to use ripgrep. The same caveats
+for the previous section apply.
+
+* Are you writing portable shell scripts intended to work in a variety of
+  environments? Great, probably not a good idea to use ripgrep! ripgrep is has
+  nowhere near the ubquity of grep, so if you do use ripgrep, you might need
+  to futz with the installation process more than you would with grep.
+* Do you care about POSIX compatibility? If so, then you can't use ripgrep
+  because it never was, isn't and never will be POSIX compatible.
+* Do you hate tools that try to do something smart? If so, ripgrep is all about
+  being smart, so you might prefer to just stick with grep.
+* Is there a particular feature of grep you rely on that ripgrep either doesn't
+  have or never will have? If the former, file a bug report, maybe ripgrep can
+  do it! If the latter, well, then, just use grep.
diff --git a/README.md b/README.md
index ca1ed5ce..047ca06c 100644
--- a/README.md
+++ b/README.md
@@ -85,9 +85,9 @@ increases the times to `2.640s` for ripgrep and `10.277s` for GNU grep.
 
 ### Why should I use ripgrep?
 
-* It can replace both The Silver Searcher and GNU grep because it is generally
-  faster than both. (N.B. It is not, strictly speaking, a "drop-in" replacement
-  for both, but the feature sets are far more similar than different.)
+* It can replace many use cases served by both The Silver Searcher and GNU grep
+  because it is generally faster than both. (See [the FAQ](FAQ.md#posix4ever)
+  for more details on whether ripgrep can truly replace grep.)
 * Like The Silver Searcher, ripgrep defaults to recursive directory search
   and won't search files ignored by your `.gitignore` files. It also ignores
   hidden and binary files by default. ripgrep also implements full support