UnbreakableMJ
diff --git a/‎Cargo.lock‎
Lines changed: 3 additions & 0 deletions b/‎Cargo.lock‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎Cargo.toml‎
Lines changed: 5 additions & 0 deletions b/‎Cargo.toml‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 62 additions & 28 deletions b/‎README.md‎
Lines changed: 62 additions & 28 deletions
diff --git a/‎src/common.rs‎
Lines changed: 39 additions & 8 deletions b/‎src/common.rs‎
Lines changed: 39 additions & 8 deletions
@@ -63,7 +63,9 @@ log = "0.4.20"
 log-panics = { version = "2", features = ["with-backtrace"] }
 crossbeam = "0.8"
 toml = "0.8"
+serde = { version = "1.0", features = ["derive"] }
 dirs = "6"
+shlex = "1.3.0"
 
 [[bin]]
 name = "dua"
@@ -82,3 +84,6 @@ build-override = { opt-level = 3 }
 
 [dev-dependencies]
 pretty_assertions = "1.0.0"
+
+[lints.clippy]
+all = "deny"
@@ -8,7 +8,7 @@
 
 ### Installation
 
-### Binary Release 
+### Binary Release
 
 #### MacOS
 
@@ -18,12 +18,14 @@ curl -LSfs https://raw.githubusercontent.com/Byron/dua-cli/master/ci/install.sh
 ```
 
 #### MacOS via [MacPorts](https://www.macports.org):
+
 ```sh
 sudo port selfupdate
 sudo port install dua-cli
 ```
 
 #### MacOS via [Homebrew](https://brew.sh)
+
 ```sh
 brew update
 brew install dua-cli
@@ -39,11 +41,13 @@ curl -LSfs https://raw.githubusercontent.com/Byron/dua-cli/master/ci/install.sh
 ```
 
 #### Windows via [Scoop](https://scoop.sh/)
+
 ```sh
 scoop install dua
 ```
 
 #### Windows via [WinGet](https://learn.microsoft.com/en-us/windows/package-manager/winget/)
+
 ```sh
 winget install Byron.dua-cli
 ```
@@ -55,9 +59,11 @@ See the [releases section][releases] for manual installation of a binary, pre-bu
 [releases]: https://github.com/Byron/dua-cli/releases
 
 #### Cargo
+
 Via `cargo`, which can be obtained using [rustup][rustup]
 
 For _Unix_…
+
 ```
 cargo install dua-cli
 
@@ -69,32 +75,37 @@ cargo install dua-cli --no-default-features --features tui-crossplatform
 ```
 
 For _Windows_, nightly features are currently required.
+
 ```
 cargo +nightly install dua-cli
 ```
 
 #### VoidLinux
+
 Via `xbps` on your VoidLinux system.
 
 ```
 xbps-install dua-cli
 ```
 
 #### Fedora
+
 Via `dnf` on your Fedora system.
 
 ```
 sudo dnf install dua-cli
 ```
 
 #### Arch Linux
+
 Via `pacman` on your ArchLinux system.
 
 ```
 sudo pacman -S dua-cli
 ```
 
 #### NixOS
+
 https://search.nixos.org/packages?query=dua
 
 Nix-shell (temporary)
@@ -112,6 +123,7 @@ NixOS configuration
 ```
 
 #### NetBSD
+
 Via `pkgin` on your NetBSD system.
 
 ```
@@ -137,9 +149,11 @@ cargo +nightly install dua-cli
 #### x-cmd
 
 [x-cmd](https://www.x-cmd.com/) is a **toolbox for Posix Shell**, offering a lightweight package manager built using shell and awk.
+
 ```sh
 x env use dua
 ```
+
 - Additionally, the [`x dua ...`](https://www.x-cmd.com/pkg/dua#dua) command is available, which automatically installs `dua` without affecting the environment, such as not modifying the `PATH` variable.
 
 ### Usage
@@ -167,6 +181,26 @@ dua i
 dua interactive
 ```
 
+### Configuration
+
+`dua` can read an optional configuration file from your OS-specific config directory:
+
+1. Linux/Unix: `$XDG_CONFIG_HOME/dua-cli/config.toml` (or the platform default config dir)
+2. macOS: `~/Library/Application Support/dua-cli/config.toml`
+3. Windows: `%APPDATA%\dua-cli\config.toml`
+
+If the file is missing, defaults are used.
+
+Currently supported options:
+
+```toml
+[keys]
+# If true, pressing <Esc> in the main pane navigates to the parent directory.
+# If true (default), pressing <Esc> in the main pane ascends to the parent directory.
+# If false, <Esc> follows the default quit behavior.
+esc_navigates_back = true
+```
+
 ### Development
 
 Please note that all the following assumes a unix system. On Windows, the linux subsystem should do the job.
@@ -197,39 +231,39 @@ Thanks to [jwalk][jwalk], all there was left to do is to write a command-line in
 
 ### Limitations
 
-* Does not show symbolic links at all if no path is provided when invoking `dua`
-  * in an effort to skip symbolic links, for now there are pruned and are not used as a root. Symbolic links will be shown if they
+- Does not show symbolic links at all if no path is provided when invoking `dua`
+  - in an effort to skip symbolic links, for now there are pruned and are not used as a root. Symbolic links will be shown if they
     are not a traversal root, but will not be followed.
-* Interactive mode only looks good in dark terminals (see [this issue](https://github.com/Byron/dua-cli/issues/13))
-* _easy fix_: file names in main window are not truncated if too large. They are cut off on the right.
-* There are plenty of examples in `tests/fixtures` which don't render correctly in interactive mode.
+- Interactive mode only looks good in dark terminals (see [this issue](https://github.com/Byron/dua-cli/issues/13))
+- _easy fix_: file names in main window are not truncated if too large. They are cut off on the right.
+- There are plenty of examples in `tests/fixtures` which don't render correctly in interactive mode.
   This can be due to graphemes not interpreted correctly. With Chinese characters for instance,
   column sizes are not correctly computed, leading to certain columns not being shown.
   In other cases, the terminal gets things wrong - I use alacritty, and with certain characters it
   performs worse than, say iTerm3.
   See https://github.com/minimaxir/big-list-of-naughty-strings/blob/master/blns.txt for the source.
-* In interactive mode, you will need about 60MB of memory for 1 million entries in the graph.
-* In interactive mode, the maximum amount of files is limited to 2^32 - 1 (`u32::max_value() - 1`) entries.
-  * One node is used as to 'virtual' root
-  * The actual amount of nodes stored might be lower, as there might be more edges than nodes, which are also limited by a `u32` (I guess)
-  * The limitation is imposed by the underlying [`petgraph`][petgraph] crate, which declares it as `unsafe` to use u64 for instance.
-  * It's possibly *UB* when that limit is reached, however, it was never observed either.
-
-### Similar Programs 
-
-* **CLI:**
-  * `du`
-  * [`dust`](https://github.com/bootandy/dust)
-  * [`dutree`](https://github.com/nachoparker/dutree)
-  * [`pdu`](https://github.com/KSXGitHub/parallel-disk-usage)
-* **TUI:**
-  * [`ncdu`](https://dev.yorhel.nl/ncdu)
-  * [`gdu`](https://github.com/dundee/gdu)
-  * [`godu`](https://github.com/viktomas/godu)
-* **GUI:**
-  * [GNOME's Disk Usage Analyzer, a.k.a. `baobab`](https://wiki.gnome.org/action/show/Apps/DiskUsageAnalyzer)
-  * [Filelight](https://apps.kde.org/filelight/)
-  
+- In interactive mode, you will need about 60MB of memory for 1 million entries in the graph.
+- In interactive mode, the maximum amount of files is limited to 2^32 - 1 (`u32::max_value() - 1`) entries.
+  - One node is used as to 'virtual' root
+  - The actual amount of nodes stored might be lower, as there might be more edges than nodes, which are also limited by a `u32` (I guess)
+  - The limitation is imposed by the underlying [`petgraph`][petgraph] crate, which declares it as `unsafe` to use u64 for instance.
+  - It's possibly _UB_ when that limit is reached, however, it was never observed either.
+
+### Similar Programs
+
+- **CLI:**
+  - `du`
+  - [`dust`](https://github.com/bootandy/dust)
+  - [`dutree`](https://github.com/nachoparker/dutree)
+  - [`pdu`](https://github.com/KSXGitHub/parallel-disk-usage)
+- **TUI:**
+  - [`ncdu`](https://dev.yorhel.nl/ncdu)
+  - [`gdu`](https://github.com/dundee/gdu)
+  - [`godu`](https://github.com/viktomas/godu)
+- **GUI:**
+  - [GNOME's Disk Usage Analyzer, a.k.a. `baobab`](https://wiki.gnome.org/action/show/Apps/DiskUsageAnalyzer)
+  - [Filelight](https://apps.kde.org/filelight/)
+
 [petgraph]: https://crates.io/crates/petgraph
 [rustup]: https://rustup.rs/
 [jwalk]: https://crates.io/crates/jwalk
 
@@ -8,7 +8,8 @@ use std::sync::atomic::{AtomicBool, Ordering};
 use std::time::Duration;
 use std::{fmt, path::Path};
 
-pub fn get_entry_or_panic(tree: &Tree, node_idx: TreeIndex) -> &EntryData {
+/// Return the entry at `node_idx` or panic if the index is invalid for `tree`.
+pub(crate) fn get_entry_or_panic(tree: &Tree, node_idx: TreeIndex) -> &EntryData {
     tree.node_weight(node_idx)
         .expect("node should always be retrievable with valid index")
 }
@@ -37,6 +38,7 @@ pub enum ByteFormat {
 }
 
 impl ByteFormat {
+    /// Return the content width (without unit suffix) needed to display values in this format.
     pub fn width(self) -> usize {
         use ByteFormat::*;
         match self {
@@ -47,6 +49,7 @@ impl ByteFormat {
             _ => 10,
         }
     }
+    /// Return the full width (value plus unit and separator) used by this format.
     pub fn total_width(self) -> usize {
         use ByteFormat::*;
         const THE_SPACE_BETWEEN_UNIT_AND_NUMBER: usize = 1;
@@ -59,15 +62,17 @@ impl ByteFormat {
             }
             + THE_SPACE_BETWEEN_UNIT_AND_NUMBER
     }
-    pub fn display(self, bytes: u128) -> ByteFormatDisplay {
+    /// Create a display adapter for `bytes` using this format.
+    pub fn display(self, bytes: u128) -> impl fmt::Display {
         ByteFormatDisplay {
             format: self,
             bytes,
         }
     }
 }
 
-pub struct ByteFormatDisplay {
+/// A lightweight display adapter created by [`ByteFormat::display`].
+struct ByteFormatDisplay {
     format: ByteFormat,
     bytes: u128,
 }
@@ -115,18 +120,23 @@ impl fmt::Display for ByteFormatDisplay {
 /// Identify the kind of sorting to apply during filesystem iteration
 #[derive(Clone)]
 pub enum TraversalSorting {
+    /// Keep filesystem iteration order as provided by the walker.
     None,
+    /// Sort entries alphabetically by file name during iteration.
     AlphabeticalByFileName,
 }
 
 /// Throttle access to an optional `io::Write` to the specified `Duration`
 #[derive(Debug)]
-pub struct Throttle {
+pub(crate) struct Throttle {
     trigger: Arc<AtomicBool>,
 }
 
 impl Throttle {
-    pub fn new(duration: Duration, initial_sleep: Option<Duration>) -> Self {
+    /// Create a new throttle that allows updates at most once per `duration`.
+    ///
+    /// If `initial_sleep` is set, the first update is delayed by that amount.
+    pub(crate) fn new(duration: Duration, initial_sleep: Option<Duration>) -> Self {
         let instance = Self {
             trigger: Default::default(),
         };
@@ -145,7 +155,8 @@ impl Throttle {
         instance
     }
 
-    pub fn throttled<F>(&self, f: F)
+    /// Execute `f` only if the throttle currently allows an update.
+    pub(crate) fn throttled<F>(&self, f: F)
     where
         F: FnOnce(),
     {
@@ -155,7 +166,7 @@ impl Throttle {
     }
 
     /// Return `true` if we are not currently throttled.
-    pub fn can_update(&self) -> bool {
+    pub(crate) fn can_update(&self) -> bool {
         self.trigger.swap(false, Ordering::Relaxed)
     }
 }
@@ -166,17 +177,31 @@ pub struct WalkOptions {
     /// The amount of threads to use. Refer to [`WalkDir::num_threads()`](https://docs.rs/jwalk/0.4.0/jwalk/struct.WalkDir.html#method.num_threads)
     /// for more information.
     pub threads: usize,
+    /// If `true`, count every hard-link occurrence independently.
     pub count_hard_links: bool,
+    /// If `true`, use apparent size (`metadata.len()`), not allocated blocks on disk.
     pub apparent_size: bool,
+    /// Sorting mode applied by the filesystem walker.
     pub sorting: TraversalSorting,
+    /// If `false`, traversal is constrained to the root filesystem/device.
     pub cross_filesystems: bool,
+    /// Canonicalized directories to skip from traversal.
     pub ignore_dirs: BTreeSet<PathBuf>,
 }
 
 type WalkDir = jwalk::WalkDirGeneric<((), Option<Result<std::fs::Metadata, jwalk::Error>>)>;
 
 impl WalkOptions {
-    pub fn iter_from_path(&self, root: &Path, root_device_id: u64, skip_root: bool) -> WalkDir {
+    /// Create an iterator over `root` honoring this walk configuration.
+    ///
+    /// `root_device_id` is used to filter entries when `cross_filesystems == false`.
+    /// If `skip_root` is `true`, the root directory itself is omitted from yielded entries.
+    pub(crate) fn iter_from_path(
+        &self,
+        root: &Path,
+        root_device_id: u64,
+        skip_root: bool,
+    ) -> WalkDir {
         let ignore_dirs = self.ignore_dirs.clone();
         let cwd = std::env::current_dir().unwrap_or_else(|_| root.to_owned());
         WalkDir::new(root)
@@ -239,11 +264,17 @@ pub struct WalkResult {
 }
 
 impl WalkResult {
+    /// Convert traversal result into a process exit code.
+    ///
+    /// Returns `0` if no I/O errors occurred, otherwise `1`.
     pub fn to_exit_code(&self) -> i32 {
         i32::from(self.num_errors > 0)
     }
 }
 
+/// Canonicalize user-provided ignore directory paths.
+///
+/// Non-canonicalizable paths are ignored.
 pub fn canonicalize_ignore_dirs(ignore_dirs: &[PathBuf]) -> BTreeSet<PathBuf> {
     let dirs = ignore_dirs
         .iter()