feat: Add --sort arg to CLI to sort by path/size/dates

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Features
 - Add `--ignore-parent` option to override `--no-ignore-parent`, see #1958 (@tmchow)
+- Add `--sort` arg to CLI to sort by path/size/dates, see #1875 and #1982 (@DeflateAwning)
 
 ## Bugfixes
 - Handle invalid working directories gracefully when using `--full-path`, see #1900 (@Xavrir).

Cargo.toml

@@ -75,6 +75,7 @@ diff = "0.1"
 tempfile = "3.27"
 filetime = "0.2"
 test-case = "3.3"
+rand = "0.10.1"
 
 [profile.dev]
 debug = "line-tables-only"

src/cli.rs

@@ -11,6 +11,7 @@ use clap::{
 use clap_complete::Shell;
 use normpath::PathExt;
 
+use crate::config::SortKey;
 use crate::error::print_error;
 use crate::exec::CommandSet;
 use crate::filesystem;
@@ -546,9 +547,26 @@ pub struct Opts {
     ///
     /// Amount of time in milliseconds to buffer, before streaming the search
     /// results to the console.
-    #[arg(long, hide = true, value_parser = parse_millis)]
+    #[arg(long, hide = true, value_parser = parse_millis, conflicts_with("sort"))]
     pub max_buffer_time: Option<Duration>,
 
+    /// Sort search results by the given key before printing or executing commands via `--exec`/`--exec-batch`.
+    ///
+    /// This option results in slower execution as parallel execution is effectively disabled.
+    ///
+    /// Warning: This option significantly increases memory usage.
+    /// All results are buffered in memory before outputting.
+    #[arg(
+        long,
+        value_name = "key",
+        value_enum,
+        hide_short_help = true,
+        help = "Sort results by: path, size, created, or modified",
+        long_help,
+        conflicts_with_all(&["list_details", "max_buffer_time"])
+    )]
+    pub sort: Option<SortKey>,
+
     ///Limit the number of search results to 'count' and quit immediately.
     #[arg(
         long,

src/config.rs

@@ -1,5 +1,6 @@
 use std::{path::PathBuf, sync::Arc, time::Duration};
 
+use clap::ValueEnum;
 use lscolors::LsColors;
 use regex::bytes::RegexSet;
 
@@ -70,6 +71,9 @@ pub struct Config {
     /// `max_buffer_time`.
     pub max_buffer_time: Option<Duration>,
 
+    /// Maximum size of the output buffer before flushing results to the console.
+    pub max_buffer_size: usize,
+
     /// `None` if the output should not be colorized. Otherwise, a `LsColors` instance that defines
     /// how to style different filetypes.
     pub ls_colors: Option<LsColors>,
@@ -133,6 +137,9 @@ pub struct Config {
 
     /// Names that should stop traversal down their parent. (e.g. https://bford.info/cachedir/).
     pub ignore_contain: Vec<String>,
+
+    /// The key to sort results by
+    pub sort_key: Option<SortKey>,
 }
 
 impl Config {
@@ -141,3 +148,15 @@ impl Config {
         self.command.is_none()
     }
 }
+
+#[derive(Copy, Clone, PartialEq, Eq, Debug, ValueEnum)]
+pub enum SortKey {
+    /// Sort by path
+    Path,
+    /// Sort by file size
+    Size,
+    /// Sort by creation time
+    Created,
+    /// Sort by modification time
+    Modified,
+}

src/filesystem.rs

@@ -59,6 +59,15 @@ pub fn is_empty(entry: &dir_entry::DirEntry) -> bool {
     }
 }
 
+pub fn file_size(entry: &dir_entry::DirEntry) -> Option<u64> {
+    let file_type = entry.file_type()?;
+    if file_type.is_dir() {
+        None
+    } else {
+        entry.metadata().map(|m| m.len())
+    }
+}
+
 #[cfg(any(unix, target_os = "redox"))]
 pub fn is_block_device(ft: fs::FileType) -> bool {
     ft.is_block_device()

src/main.rs

@@ -17,6 +17,7 @@ use std::env;
 use std::io::IsTerminal;
 use std::path::Path;
 use std::sync::Arc;
+use std::time::Duration;
 
 use anyhow::{Context, Result, anyhow, bail};
 use clap::{CommandFactory, Parser};
@@ -33,6 +34,7 @@ use crate::filetypes::FileTypes;
 use crate::filter::OwnerFilter;
 use crate::filter::TimeFilter;
 use crate::regex_helper::{pattern_has_uppercase_char, pattern_matches_strings_with_leading_dot};
+use crate::walk::DEFAULT_MAX_BUFFER_LENGTH;
 
 // We use jemalloc for performance reasons, see https://github.com/sharkdp/fd/pull/481
 // FIXME: re-enable jemalloc on macOS, see comment in Cargo.toml file for more infos
@@ -273,7 +275,16 @@ fn construct_config(mut opts: Opts, pattern_regexps: &[String]) -> Result<Config
         min_depth: opts.min_depth(),
         prune: opts.prune,
         threads: opts.threads().get(),
-        max_buffer_time: opts.max_buffer_time,
+        max_buffer_time: match opts.sort {
+            // If sorting is enabled, then set max_buffer_time to practically infinity.
+            Some(_) => Some(Duration::from_secs(3600 * 24 * 365 * 10)), // 10 years - arbitrarily-large.
+            None => opts.max_buffer_time,
+        },
+        max_buffer_size: match opts.sort {
+            // If sorting is enabled, allow a practically infinite buffer size.
+            Some(_) => usize::MAX,
+            None => DEFAULT_MAX_BUFFER_LENGTH,
+        },
         ls_colors,
         hyperlink,
         interactive_terminal,
@@ -336,6 +347,7 @@ fn construct_config(mut opts: Opts, pattern_regexps: &[String]) -> Result<Config
         max_results: opts.max_results(),
         strip_cwd_prefix: opts.strip_cwd_prefix(|| !(opts.null_separator || has_command)),
         ignore_contain: opts.ignore_contain,
+        sort_key: opts.sort,
     })
 }
 

src/walk.rs

@@ -6,7 +6,7 @@ use std::path::PathBuf;
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex, MutexGuard};
 use std::thread;
-use std::time::{Duration, Instant};
+use std::time::{Duration, Instant, SystemTime};
 
 use anyhow::{Result, anyhow};
 use crossbeam_channel::{Receiver, RecvTimeoutError, SendError, Sender, bounded};
@@ -15,7 +15,7 @@ use ignore::overrides::{Override, OverrideBuilder};
 use ignore::{WalkBuilder, WalkParallel, WalkState};
 use regex::bytes::Regex;
 
-use crate::config::Config;
+use crate::config::{Config, SortKey};
 use crate::dir_entry::DirEntry;
 use crate::error::print_error;
 use crate::exec;
@@ -24,7 +24,7 @@ use crate::filesystem;
 use crate::output;
 
 /// The receiver thread can either be buffering results or directly streaming to the console.
-#[derive(PartialEq)]
+#[derive(Copy, Clone, PartialEq)]
 enum ReceiverMode {
     /// Receiver is still buffering in order to sort the results, if the search finishes fast
     /// enough.
@@ -122,7 +122,8 @@ impl BatchSender {
 }
 
 /// Maximum size of the output buffer before flushing results to the console
-const MAX_BUFFER_LENGTH: usize = 1000;
+pub const DEFAULT_MAX_BUFFER_LENGTH: usize = 1000;
+
 /// Default duration until output buffering switches to streaming.
 const DEFAULT_MAX_BUFFER_TIME: Duration = Duration::from_millis(100);
 
@@ -165,7 +166,7 @@ impl<'a, W: Write> ReceiverBuffer<'a, W> {
             stdout,
             mode: ReceiverMode::Buffering,
             deadline,
-            buffer: Vec::with_capacity(MAX_BUFFER_LENGTH),
+            buffer: Vec::with_capacity(config.max_buffer_size.min(10_000)),
             num_results: 0,
         }
     }
@@ -208,7 +209,7 @@ impl<'a, W: Write> ReceiverBuffer<'a, W> {
                             match self.mode {
                                 ReceiverMode::Buffering => {
                                     self.buffer.push(dir_entry);
-                                    if self.buffer.len() > MAX_BUFFER_LENGTH {
+                                    if self.buffer.len() > self.config.max_buffer_size {
                                         self.stream()?;
                                     }
                                 }
@@ -241,6 +242,7 @@ impl<'a, W: Write> ReceiverBuffer<'a, W> {
                 self.stream()?;
             }
             Err(RecvTimeoutError::Disconnected) => {
+                // Note: This branch is called when all the results are walked/exhausted.
                 return self.stop();
             }
         }
@@ -280,9 +282,22 @@ impl<'a, W: Write> ReceiverBuffer<'a, W> {
 
     /// Stop looping.
     fn stop(&mut self) -> Result<(), ExitCode> {
-        if self.mode == ReceiverMode::Buffering {
-            self.buffer.sort();
-            self.stream()?;
+        match (self.mode, self.config.sort_key) {
+            (ReceiverMode::Buffering, None) => {
+                self.buffer.sort();
+                self.stream()?;
+            }
+            (ReceiverMode::Buffering, Some(sort_key)) => {
+                sort_dir_entry_results(&mut self.buffer, sort_key);
+                self.stream()?;
+            }
+            (ReceiverMode::Streaming, None) => {}
+            (ReceiverMode::Streaming, Some(_)) => {
+                // We force Buffering mode in Config construction if --sort is set by setting the timeout to almost infinity.
+                unreachable!(
+                    "--sort cannot work in Streaming mode. Buffering mode is forced in Config construction."
+                );
+            }
         }
 
         if self.config.quiet {
@@ -407,12 +422,23 @@ impl WorkerState {
     /// threads (for --exec).
     fn receive(&self, rx: Receiver<Batch>) -> ExitCode {
         let config = &self.config;
-
         // This will be set to `Some` if the `--exec` argument was supplied.
         if let Some(ref cmd) = config.command {
-            if cmd.in_batch_mode() {
+            if let Some(sort_key) = config.sort_key {
+                // With --sort, we must collect all results before dispatching,
+                // and run sequentially so the order is preserved.
+                let mut results: Vec<WorkerResult> = rx.into_iter().flatten().collect();
+                sort_worker_results(&mut results, sort_key);
+                if cmd.in_batch_mode() {
+                    exec::batch(results, cmd, config)
+                } else {
+                    exec::job(results, cmd, config)
+                }
+            } else if cmd.in_batch_mode() {
+                // Batch mode without sorting.
                 exec::batch(rx.into_iter().flatten(), cmd, config)
             } else {
+                // No sort. Not Batch mode. Dispatch jobs across a thread pool as results stream in.
                 thread::scope(|scope| {
                     // Each spawned job will store its thread handle in here.
                     let threads = config.threads;
@@ -663,6 +689,44 @@ impl WorkerState {
     }
 }
 
+type SortKeyValueFn = Box<dyn Fn(&DirEntry) -> Option<SortKeyValue>>;
+
+fn dir_entry_key_fn(sort_key: SortKey) -> SortKeyValueFn {
+    match sort_key {
+        SortKey::Path => Box::new(|e| Some(SortKeyValue::Path(e.path().to_path_buf()))),
+        SortKey::Size => Box::new(|e| filesystem::file_size(e).map(SortKeyValue::Size)),
+        SortKey::Created => {
+            Box::new(|e| e.metadata().map(|m| SortKeyValue::Time(m.created().ok())))
+        }
+        SortKey::Modified => {
+            Box::new(|e| e.metadata().map(|m| SortKeyValue::Time(m.modified().ok())))
+        }
+    }
+}
+
+fn sort_dir_entry_results(results: &mut [DirEntry], sort_key: SortKey) {
+    let key_fn = dir_entry_key_fn(sort_key);
+    results.sort_by_cached_key(|e| key_fn(e));
+}
+
+fn sort_worker_results(results: &mut [WorkerResult], sort_key: SortKey) {
+    let key_fn = dir_entry_key_fn(sort_key);
+    results.sort_by_cached_key(|r| match r {
+        WorkerResult::Entry(e) => key_fn(e),
+        WorkerResult::Error(_) => None,
+    });
+}
+
+/// Comparable key values, one variant per SortKey.
+/// None sorts last via Option<T: Ord>'s natural ordering (None > Some).
+/// Only like enum variants will be compared (e.g., Path < Size will never be compared).
+#[derive(Eq, PartialEq, Ord, PartialOrd)]
+enum SortKeyValue {
+    Path(PathBuf),
+    Size(u64),
+    Time(Option<SystemTime>),
+}
+
 fn search_str_for_entry<'a>(
     entry_path: &'a std::path::Path,
     full_path_base: Option<&std::path::Path>,