doc: note cases of exorbitant memory usage

Fixes #1189

CHANGELOG.md

@@ -55,14 +55,14 @@ Bug fixes:
   ripgrep no longer hangs when searching `/proc` with a zombie process present.
 * [BUG #1091](https://github.com/BurntSushi/ripgrep/issues/1091):
   Add note about inverted flags to the man page.
+* [BUG #1093](https://github.com/BurntSushi/ripgrep/pull/1093):
+  Fix handling of literal slashes in gitignore patterns.
 * [BUG #1095](https://github.com/BurntSushi/ripgrep/issues/1095):
   Fix corner cases involving the `--crlf` flag.
 * [BUG #1103](https://github.com/BurntSushi/ripgrep/issues/1103):
   Clarify what `--encoding auto` does.
 * [BUG #1106](https://github.com/BurntSushi/ripgrep/issues/1106):
   `--files-with-matches` and `--files-without-match` work with one file.
-* [BUG #1093](https://github.com/BurntSushi/ripgrep/pull/1093):
-  Fix handling of literal slashes in gitignore patterns.
 * [BUG #1121](https://github.com/BurntSushi/ripgrep/issues/1121):
   Fix bug that was triggering Windows antimalware when using the --files flag.
 * [BUG #1125](https://github.com/BurntSushi/ripgrep/issues/1125),
@@ -76,6 +76,8 @@ Bug fixes:
   Fix handling of repeated `**` patterns in gitignore files.
 * [BUG #1176](https://github.com/BurntSushi/ripgrep/issues/1176):
   Fix bug where `-F`/`-x` weren't applied to patterns given via `-f`.
+* [BUG #1189](https://github.com/BurntSushi/ripgrep/issues/1189):
+  Document cases where ripgrep may use a lot of memory.
 
 
 0.10.0 (2018-09-07)

doc/rg.1.txt.tpl

@@ -192,6 +192,21 @@ file that is simultaneously truncated. This behavior can be avoided by passing
 the *--no-mmap* flag which will forcefully disable the use of memory maps in
 all cases.
 
+ripgrep may use a large amount of memory depending on a few factors. Firstly,
+if ripgrep uses parallelism for search (the default), then the entire output
+for each individual file is buffered into memory in order to prevent
+interleaving matches in the output. To avoid this, you can disable parallelism
+with the *-j1* flag. Secondly, ripgrep always needs to have at least a single
+line in memory in order to execute a search. A file with a very long line can
+thus cause ripgrep to use a lot of memory. Generally, this only occurs when
+searching binary data with the *-a* flag enabled. (When the *-a* flag isn't
+enabled, ripgrep will replace all NUL bytes with line terminators, which
+typically prevents exorbitant memory usage.) Thirdly, when ripgrep searches
+a large file using a memory map, the process will report its resident memory
+usage as the size of the file. However, this does not mean ripgrep actually
+needed to use that much memory; the operating system will generally handle this
+for you.
+
 
 VERSION
 -------