From 00225a035baa62fbbbcb8373d0ad5e45472f56bc Mon Sep 17 00:00:00 2001
From: Andrew Gallant <jamslam@gmail.com>
Date: Wed, 22 Nov 2023 16:51:18 -0500
Subject: [PATCH] doc: improve --sort=path

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

Fixes #2418
---
 CHANGELOG.md              |  2 ++
 crates/core/flags/defs.rs | 15 +++++++++++----
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e91102bbb..de6c7230d 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 38611759e..cd7cdd32d 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.