doc: improve --sort=path

This clarifies that the paths are not sorted in a fully lexicographic
order, but that / is treated specially.

Fixes #2418

2 files changed, 13 insertions, 4 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e91102bb..de6c7230 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -79,6 +79,8 @@ Bug fixes:
   Make `-p/--pretty` override flags like `--no-line-number`.
 * [BUG #2392](https://github.com/BurntSushi/ripgrep/issues/2392):
   Improve global git config parsing of the `excludesFile` field.
+* [BUG #2418](https://github.com/BurntSushi/ripgrep/pull/2418):
+  Clarify sorting semantics of `--sort=path`.
 * [BUG #2458](https://github.com/BurntSushi/ripgrep/pull/2458):
   Make `--trim` run before `-M/--max-columns` takes effect.
 * [BUG #2479](https://github.com/BurntSushi/ripgrep/issues/2479):
diff --git a/crates/core/flags/defs.rs b/crates/core/flags/defs.rs
index 38611759..cd7cdd32 100644
--- a/crates/core/flags/defs.rs
+++ b/crates/core/flags/defs.rs
@@ -6205,7 +6205,10 @@ for this flag are:
 (Default) Do not sort results. Fastest. Can be multi-threaded.
 .TP 12
 \fBpath\fP
-Sort by file path. Always single-threaded.
+Sort by file path. Always single-threaded. The order is determined by sorting
+files in each directory entry during traversal. This means that given the files
+\fBa/b\fP and \fBa+\fP, the latter will sort after the former even though
+\fB+\fP would normally sort before \fB/\fP.
 .TP 12
 \fBmodified\fP
 Sort by the last modified time on a file. Always single-threaded.
@@ -6220,8 +6223,8 @@ If the chosen (manually or by-default) sorting criteria isn't available on your
 system (for example, creation time is not available on ext4 file systems), then
 ripgrep will attempt to detect this, print an error and exit without searching.
 .sp
-To sort results in reverse or descending order, use the \flag{sortr} flag. Also,
-this flag overrides \flag{sortr}.
+To sort results in reverse or descending order, use the \flag{sortr} flag.
+Also, this flag overrides \flag{sortr}.
 .sp
 Note that sorting results currently always forces ripgrep to abandon
 parallelism and run in a single thread.
@@ -6303,7 +6306,11 @@ for this flag are:
 (Default) Do not sort results. Fastest. Can be multi-threaded.
 .TP 12
 \fBpath\fP
-Sort by file path. Always single-threaded.
+Sort by file path. Always single-threaded. The order is determined by sorting
+files in each directory entry during traversal. This means that given the files
+\fBa/b\fP and \fBa+\fP, the latter will sort before the former even though
+\fB+\fP would normally sort after \fB/\fP when doing a reverse lexicographic
+sort.
 .TP 12
 \fBmodified\fP
 Sort by the last modified time on a file. Always single-threaded.