feat: option to prevent cross-filesystem traversal

Cargo.toml

@@ -93,4 +93,4 @@ pretty_assertions = "1.4.1"
 rand = "0.10.0"
 
 [lints.rust]
-unexpected_cfgs = { level = "warn", check-cfg = ['cfg(pdu_test_skip_fs_errors)'] }
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(pdu_test_skip_fs_errors)', 'cfg(pdu_test_skip_cross_device)'] }

README.md

@@ -61,7 +61,6 @@ The benchmark was generated by [a GitHub Workflow](https://github.com/KSXGitHub/
 
 * Ignorant of reflinks (from COW filesystems such as BTRFS and ZFS).
 * Does not follow symbolic links.
-* Does not differentiate filesystems: Mounted folders are counted as normal folders.
 * The runtime is optimized at the expense of binary size.
 
 ## Usage

USAGE.md

@@ -101,6 +101,13 @@ Do not sort the branches in the tree.
 
 Prevent filesystem error messages from appearing in stderr.
 
+<a id="option-x" name="option-x"></a><a id="one-file-system" name="one-file-system"></a>
+### `--one-file-system`
+
+* _Aliases:_ `-x`.
+
+Skip directories on different filesystems.
+
 <a id="option-p" name="option-p"></a><a id="progress" name="progress"></a>
 ### `--progress`
 

exports/completion.bash

@@ -23,7 +23,7 @@ _pdu() {
 
     case "${cmd}" in
         pdu)
-            opts="-b -H -q -d -w -m -s -p -h -V --json-input --json-output --bytes-format --detect-links --dedupe-links --deduplicate-hardlinks --top-down --align-right --quantity --depth --max-depth --width --total-width --column-width --min-ratio --no-sort --no-errors --silent-errors --progress --threads --omit-json-shared-details --omit-json-shared-summary --help --version [FILES]..."
+            opts="-b -H -q -d -w -m -s -x -p -h -V --json-input --json-output --bytes-format --detect-links --dedupe-links --deduplicate-hardlinks --top-down --align-right --quantity --depth --max-depth --width --total-width --column-width --min-ratio --no-sort --no-errors --silent-errors --one-file-system --progress --threads --omit-json-shared-details --omit-json-shared-summary --help --version [FILES]..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

exports/completion.elv

@@ -44,6 +44,8 @@ set edit:completion:arg-completer[pdu] = {|@words|
             cand -s 'Prevent filesystem error messages from appearing in stderr'
             cand --silent-errors 'Prevent filesystem error messages from appearing in stderr'
             cand --no-errors 'Prevent filesystem error messages from appearing in stderr'
+            cand -x 'Skip directories on different filesystems'
+            cand --one-file-system 'Skip directories on different filesystems'
             cand -p 'Report progress being made at the expense of performance'
             cand --progress 'Report progress being made at the expense of performance'
             cand --omit-json-shared-details 'Do not output `.shared.details` in the JSON output'

exports/completion.fish

@@ -16,6 +16,7 @@ complete -c pdu -l top-down -d 'Print the tree top-down instead of bottom-up'
 complete -c pdu -l align-right -d 'Set the root of the bars to the right'
 complete -c pdu -l no-sort -d 'Do not sort the branches in the tree'
 complete -c pdu -s s -l silent-errors -l no-errors -d 'Prevent filesystem error messages from appearing in stderr'
+complete -c pdu -s x -l one-file-system -d 'Skip directories on different filesystems'
 complete -c pdu -s p -l progress -d 'Report progress being made at the expense of performance'
 complete -c pdu -l omit-json-shared-details -d 'Do not output `.shared.details` in the JSON output'
 complete -c pdu -l omit-json-shared-summary -d 'Do not output `.shared.summary` in the JSON output'

exports/completion.ps1

@@ -47,6 +47,8 @@ Register-ArgumentCompleter -Native -CommandName 'pdu' -ScriptBlock {
             [CompletionResult]::new('-s', '-s', [CompletionResultType]::ParameterName, 'Prevent filesystem error messages from appearing in stderr')
             [CompletionResult]::new('--silent-errors', '--silent-errors', [CompletionResultType]::ParameterName, 'Prevent filesystem error messages from appearing in stderr')
             [CompletionResult]::new('--no-errors', '--no-errors', [CompletionResultType]::ParameterName, 'Prevent filesystem error messages from appearing in stderr')
+            [CompletionResult]::new('-x', '-x', [CompletionResultType]::ParameterName, 'Skip directories on different filesystems')
+            [CompletionResult]::new('--one-file-system', '--one-file-system', [CompletionResultType]::ParameterName, 'Skip directories on different filesystems')
             [CompletionResult]::new('-p', '-p', [CompletionResultType]::ParameterName, 'Report progress being made at the expense of performance')
             [CompletionResult]::new('--progress', '--progress', [CompletionResultType]::ParameterName, 'Report progress being made at the expense of performance')
             [CompletionResult]::new('--omit-json-shared-details', '--omit-json-shared-details', [CompletionResultType]::ParameterName, 'Do not output `.shared.details` in the JSON output')

exports/completion.zsh

@@ -49,6 +49,8 @@ block-count\:"Count numbers of blocks"))' \
 '-s[Prevent filesystem error messages from appearing in stderr]' \
 '--silent-errors[Prevent filesystem error messages from appearing in stderr]' \
 '--no-errors[Prevent filesystem error messages from appearing in stderr]' \
+'-x[Skip directories on different filesystems]' \
+'--one-file-system[Skip directories on different filesystems]' \
 '-p[Report progress being made at the expense of performance]' \
 '--progress[Report progress being made at the expense of performance]' \
 '--omit-json-shared-details[Do not output \`.shared.details\` in the JSON output]' \

exports/long.help

@@ -74,6 +74,9 @@ Options:
 
           [aliases: --no-errors]
 
+  -x, --one-file-system
+          Skip directories on different filesystems
+
   -p, --progress
           Report progress being made at the expense of performance
 

exports/short.help

@@ -32,6 +32,8 @@ Options:
           Do not sort the branches in the tree
   -s, --silent-errors
           Prevent filesystem error messages from appearing in stderr [aliases: --no-errors]
+  -x, --one-file-system
+          Skip directories on different filesystems
   -p, --progress
           Report progress being made at the expense of performance
       --threads <THREADS>

src/app.rs

@@ -133,6 +133,13 @@ impl App {
                 .pipe(Err);
         }
 
+        #[cfg(not(unix))]
+        if self.args.one_file_system {
+            return crate::runtime_error::UnsupportedFeature::OneFileSystem
+                .pipe(RuntimeError::UnsupportedFeature)
+                .pipe(Err);
+        }
+
         let threads = match self.args.threads {
             Threads::Auto => {
                 let disks = Disks::new_with_refreshed_list();
@@ -288,6 +295,7 @@ impl App {
                     bytes_format,
                     top_down,
                     align_right,
+                    one_file_system,
                     max_depth,
                     min_ratio,
                     no_sort,
@@ -304,6 +312,7 @@ impl App {
                     files,
                     json_output: JsonOutputParam::from_cli_flags(json_output, omit_json_shared_details, omit_json_shared_summary),
                     column_width_distribution,
+                    one_file_system,
                     max_depth,
                     min_ratio,
                     no_sort,

src/app/sub.rs

@@ -37,6 +37,8 @@ where
     pub bar_alignment: BarAlignment,
     /// Distribution and number of characters/blocks can be placed in a line.
     pub column_width_distribution: ColumnWidthDistribution,
+    /// Skip directories on different filesystems.
+    pub one_file_system: bool,
     /// Maximum number of levels that should be visualized.
     pub max_depth: Depth,
     /// [Get the size](GetSize) of files/directories.
@@ -68,6 +70,7 @@ where
             direction,
             bar_alignment,
             column_width_distribution,
+            one_file_system,
             max_depth,
             size_getter,
             hardlinks_handler,
@@ -86,6 +89,7 @@ where
                     root,
                     size_getter,
                     hardlinks_recorder: &hardlinks_handler,
+                    one_file_system,
                     max_depth,
                 }
                 .into()

src/args.rs

@@ -155,6 +155,11 @@ pub struct Args {
     #[clap(long, short, visible_alias = "no-errors")]
     pub silent_errors: bool,
 
+    /// Skip directories on different filesystems.
+    #[clap(long, short = 'x')]
+    #[cfg_attr(not(unix), clap(hide = true))]
+    pub one_file_system: bool,
+
     /// Report progress being made at the expense of performance.
     #[clap(long, short)]
     pub progress: bool,

src/fs_tree_builder.rs

@@ -7,6 +7,7 @@ use super::{
     size,
     tree_builder::{Info, TreeBuilder},
 };
+use device_id::get_device_id;
 use pipe_trait::Pipe;
 use std::{
     fs::{read_dir, symlink_metadata},
@@ -32,6 +33,7 @@ use std::{
 ///     hardlinks_recorder: &HardlinkIgnorant,
 ///     size_getter: GetApparentSize,
 ///     reporter: &ErrorOnlyReporter::new(ErrorReport::SILENT),
+///     one_file_system: false,
 ///     max_depth: 10,
 /// };
 /// let data_tree: DataTree<OsStringDisplay, Bytes> = builder.into();
@@ -52,6 +54,8 @@ where
     pub hardlinks_recorder: &'a HardlinksRecorder,
     /// Reports progress to external system.
     pub reporter: &'a Report,
+    /// Skip directories on different filesystems.
+    pub one_file_system: bool,
     /// Deepest level of descendant display in the graph. The sizes beyond the max depth still count toward total.
     pub max_depth: u64,
 }
@@ -72,16 +76,35 @@ where
             size_getter,
             hardlinks_recorder,
             reporter,
+            one_file_system,
             max_depth,
         } = builder;
 
+        // `root` would be inspected multiple times, but its impact on performance is insignificant
+        // before the (usually) massive fs tree `root` contains.
+        let root_dev = if one_file_system {
+            match symlink_metadata(&root) {
+                Err(error) => {
+                    reporter.report(Event::EncounterError(ErrorReport {
+                        operation: SymlinkMetadata,
+                        path: &root,
+                        error,
+                    }));
+                    return DataTree::file(OsStringDisplay::os_string_from(&root), Size::default());
+                }
+                Ok(stats) => Some(get_device_id(&stats)),
+            }
+        } else {
+            None
+        };
+
         TreeBuilder::<PathBuf, OsStringDisplay, Size, _, _> {
             name: OsStringDisplay::os_string_from(&root),
 
             path: root,
 
             get_info: |path| {
-                let (is_dir, size) = match symlink_metadata(path) {
+                let (is_dir, size, same_device) = match symlink_metadata(path) {
                     Err(error) => {
                         reporter.report(Event::EncounterError(ErrorReport {
                             operation: SymlinkMetadata,
@@ -96,18 +119,20 @@ where
                     Ok(stats) => {
                         // `stats` should be dropped ASAP to avoid piling up kernel memory usage
                         let is_dir = stats.is_dir();
+                        let same_device =
+                            root_dev.is_none_or(|root_dev| get_device_id(&stats) == root_dev);
                         let size = size_getter.get_size(&stats);
                         reporter.report(Event::ReceiveData(size));
                         hardlinks_recorder
                             .record_hardlinks(RecordHardlinksArgument::new(
                                 path, &stats, size, reporter,
                             ))
                             .ok(); // ignore the error for now
-                        (is_dir, size)
+                        (is_dir, size, same_device)
                     }
                 };
 
-                let children: Vec<_> = if is_dir {
+                let children: Vec<_> = if is_dir && same_device {
                     match read_dir(path) {
                         Err(error) => {
                             reporter.report(Event::EncounterError(ErrorReport {
@@ -145,3 +170,5 @@ where
         .into()
     }
 }
+
+mod device_id;

src/fs_tree_builder/device_id.rs

@@ -0,0 +1,69 @@
+/// Unique identifier for a device or filesystem.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct DeviceId(Inner);
+
+#[cfg(unix)]
+type Inner = u64;
+
+#[cfg(not(unix))]
+type Inner = ();
+
+/// Retrieve the [`DeviceId`] from filesystem metadata.
+#[cfg(unix)]
+pub(crate) fn get_device_id(stats: &std::fs::Metadata) -> DeviceId {
+    use std::os::unix::fs::MetadataExt;
+    DeviceId(stats.dev())
+}
+
+/// Retrieve the [`DeviceId`] from filesystem metadata.
+///
+/// On unsupported platforms, all entries share the same [`DeviceId`],
+/// effectively disabling cross-device detection.
+#[cfg(not(unix))]
+pub(crate) fn get_device_id(_stats: &std::fs::Metadata) -> DeviceId {
+    DeviceId(())
+}
+
+#[cfg(test)]
+#[cfg(unix)]
+mod tests {
+    use super::get_device_id;
+    use std::fs::symlink_metadata;
+
+    #[test]
+    fn same_filesystem_returns_equal_ids() {
+        let root_stats = symlink_metadata("/").expect("stat /");
+        let root_stats2 = symlink_metadata("/").expect("stat / again");
+        assert_eq!(
+            get_device_id(&root_stats),
+            get_device_id(&root_stats2),
+            "same path should yield the same DeviceId",
+        );
+    }
+
+    /// `/proc` is a virtual filesystem mounted separately from `/` on Linux.
+    #[test]
+    #[cfg(target_os = "linux")]
+    fn different_filesystem_returns_different_ids() {
+        let root_stats = symlink_metadata("/").expect("stat /");
+        let proc_stats = symlink_metadata("/proc").expect("stat /proc");
+        assert_ne!(
+            get_device_id(&root_stats),
+            get_device_id(&proc_stats),
+            "/ and /proc should be on different devices",
+        );
+    }
+
+    /// `/dev` is a separate filesystem (`devfs`) from `/` on macOS.
+    #[test]
+    #[cfg(target_os = "macos")]
+    fn different_filesystem_returns_different_ids() {
+        let root_stats = symlink_metadata("/").expect("stat /");
+        let dev_stats = symlink_metadata("/dev").expect("stat /dev");
+        assert_ne!(
+            get_device_id(&root_stats),
+            get_device_id(&dev_stats),
+            "/ and /dev should be on different devices",
+        );
+    }
+}

src/runtime_error.rs

@@ -32,6 +32,10 @@ pub enum UnsupportedFeature {
     #[cfg(not(unix))]
     #[display("Feature --deduplicate-hardlinks is not available on this platform")]
     DeduplicateHardlink,
+    /// Using `--one-file-system` on non-POSIX.
+    #[cfg(not(unix))]
+    #[display("Feature --one-file-system is not available on this platform")]
+    OneFileSystem,
 }
 
 impl From<Infallible> for RuntimeError {

tests/_utils.rs

@@ -373,6 +373,7 @@ where
                 panic!("Unexpected call to report_error: {error:?}")
             }),
             root: root.join(suffix),
+            one_file_system: false,
             max_depth: 10,
         }
         .pipe(DataTree::<OsStringDisplay, Size>::from)

tests/cli_errors.rs

@@ -148,6 +148,7 @@ fn fs_errors() {
         size_getter: GetApparentSize,
         hardlinks_recorder: &HardlinkIgnorant,
         reporter: &ErrorOnlyReporter::new(ErrorReport::SILENT),
+        one_file_system: false,
         max_depth: 10,
     };
     let mut data_tree: DataTree<OsStringDisplay, _> = builder.into();

tests/json.rs

@@ -85,6 +85,7 @@ fn json_output() {
         size_getter: GetApparentSize,
         hardlinks_recorder: &HardlinkIgnorant,
         reporter: &ErrorOnlyReporter::new(ErrorReport::SILENT),
+        one_file_system: false,
         max_depth: 10,
     };
     let expected = builder