dust

repository·master·Indexed 11 days ago

A Rust-based disk usage analyzer providing a visual, hierarchical overview of disk space consumption. It serves as a more intuitive version of `du`, automatically identifying the largest subdirectories and files with support for regex filtering, time-based filtering, and custom TOML configuration. Version 1.2.4.

Tokens: 4.9K
Snippets: 14
Records: 25
Agent score: 95%

What's inside dust

Use Dust to analyze disk usage
master
Dust provides an intuitive, colored overview of disk usage. It automatically finds the largest subdirectories and files without needing manual depth or human-readable flags.
By default, it lists a number of entries roughly equal to your terminal height. You can customize this using the -n flag.
Basic Usage
- dust: Analyze current directory.
- dust <dir>: Analyze a specific directory.
- dust <dir1> <dir2>: Analyze multiple directories.
Common Tasks
- Show more/fewer entries: Use -n <number> (e.g., dust -n 50).
- Show only directories: dust -D
- Show only files: dust -F
- Show full paths: dust -p
- Show specific depth: dust -d <depth>
- Filter by size: dust -z <size> (e.g., dust -z 10M to show only items larger than 10MB).
- Filter by regex: dust -e <regex> (include) or dust -v <regex> (exclude).
```
dust -n 30
dust -d 3
dust -z 10M
```
https://github.com/bootandy/dust/blob/master/README.md
Install Dust
master
You can install dust using several methods depending on your operating system and preferred package manager.
Quick Install (Linux, macOS, Windows)
```
curl -sSfL https://raw.githubusercontent.com/bootandy/dust/refs/heads/master/install.sh | sh
```
Package Managers
- Cargo: cargo install du-dust
- Homebrew (macOS/Linux): brew install dust
- DNF (Fedora): sudo dnf install du-dust
- Snap (Ubuntu): snap install dust (Note: Snap version is restricted to the /home directory)
- mise: mise use -g dust
- Pacstall (Debian/Ubuntu): pacstall -I dust-bin
- Anaconda: conda install -c conda-forge dust
- deb-get (Debian/Ubuntu): deb-get install du-dust
- x-cmd: x env use dust
- Scoop (Windows): scoop install dust
Manual Binary Installation
1. Download the Linux/Mac binary from the Releases page.
2. Unzip the file: tar -xvf _downloaded_file.tar.gz
3. Move to your executable path: sudo mv dust /usr/local/bin/
https://github.com/bootandy/dust/blob/master/README.md
Configure Dust output formats
master
Dust supports multiple output formats to suit different use cases. The output format can be controlled via CLI flags or a configuration file.
Supported formats include:
- Standard/Default: A visual tree representation with bars and colors.
- JSON: A machine-readable format. Use the --output-json flag to force JSON output. When JSON is used, the structure follows the DisplayNode schema.
https://github.com/bootandy/dust/blob/master/src/main.rs
Filter by file modification, access, or change time
master
Dust allows filtering files based on their timestamps. The time values are relative to the current date's epoch (midnight).
When providing a value, you can prefix it with operators to define the filter logic:
- +<value>: Files modified/accessed/changed less than the specified time (newer than).
- -<value>: Files modified/accessed/changed greater than the specified time (older than).
- <value> (no prefix): Files modified/accessed/changed equal to the specified time (within the window).
Note: The value represents a number of days.
https://github.com/bootandy/dust/blob/master/src/config.rs
Use size suffixes for min-size filtering
master
When setting the min-size configuration or flag, you can use various human-readable suffixes. Dust supports both binary (IEC) and decimal (SI) units.
Examples of supported formats:
- 10Ki or 10KiB (Binary/IEC)
- 10MiB or 10M (Binary/IEC)
- 10Mb or 10KB (Decimal/SI)
- 2Gi (Binary/IEC)
https://github.com/bootandy/dust/blob/master/src/config.rs
Configure Dust via config.toml
master
You can persist your preferred dust settings in a configuration file. Dust looks for the config in the following locations (in order):
1. $XDG_CONFIG_HOME/dust/config.toml
2. ~/.config/dust/config.toml
3. ~/.dust.toml
Example configuration to always enable reverse output:
```
reverse = true
```
https://github.com/bootandy/dust/blob/master/README.md
How Dust processes input paths
master
Dust determines which directories to scan based on a hierarchy of sources:
1. Config/CLI Files: If a path is provided via --files0-from (null-terminated) or --files-from (newline-terminated), Dust reads those files to get the target paths.
2. CLI Parameters: If no files are specified via the config/CLI flags, Dust uses the positional parameters provided on the command line.
3. Default: If no parameters or files are provided, Dust defaults to scanning the current directory (.).
Input can also be piped via stdin using the - path convention.
https://github.com/bootandy/dust/blob/master/src/main.rs
Configure Dust via TOML config files
master
Dust can be configured using a TOML file. If no path is explicitly provided via the command line, Dust searches for configuration files in the following locations:
1. ~/.dust.toml (in your home directory)
2. $XDG_CONFIG_HOME/dust/config.toml (if XDG_CONFIG_HOME is set)
3. ~/.config/dust/config.toml (default fallback if XDG_CONFIG_HOME is not set)
Configuration settings in the file follow kebab-case naming. Command-line arguments will override settings found in the configuration file.
https://github.com/bootandy/dust/blob/master/src/config.rs
Filter directory contents with Regex
master
You can include or exclude directories and files from the scan using regular expressions:
- Include: Use --filter <REGEX> to only show items matching the pattern.
- Exclude: Use --invert-filter <REGEX> to hide items matching the pattern.
- File-based Exclusions: Use --ignore-all-in-file <PATH> to provide a file containing regex patterns for exclusion.
https://github.com/bootandy/dust/blob/master/src/main.rs
Configure `InitialDisplayData` for rendering
master
Use the InitialDisplayData struct to control how the output is formatted. Key configuration fields include:
- short_paths: If true, displays only the base name of the directory instead of the full path.
- is_reversed: If true, reverses the tree order (useful for certain terminal scrolling behaviors).
- colors_on: Enables ANSI color output (uses ls_colors logic).
- by_filecount: If true, the size column displays the number of files instead of bytes.
- by_filetime: If Some(FileTime), the size column displays file modification timestamps.
- is_screen_reader: If true, simplifies output for accessibility (removes bars, uses depth numbers).
- output_format: A string determining the unit scale (e.g., "si" for decimal units or "count" for file counts).
- bars_on_right: If true, the percentage bar chart is rendered on the right side of the name.
```
pub struct InitialDisplayData {
    pub short_paths: bool,
    pub is_reversed: bool,
    pub colors_on: bool,
    pub by_filecount: bool,
    pub by_filetime: Option<FileTime>,
    pub is_screen_reader: bool,
    pub output_format: String,
    pub bars_on_right: bool,
}
```
https://github.com/bootandy/dust/blob/master/src/display.rs
Configure aggregation and filtering via AggregateData
master
The AggregateData struct defines how disk usage data is filtered, aggregated, and displayed. Use this to control the scope and depth of the output.
Key fields:
- min_size: An Option<usize> to filter nodes by a minimum size threshold.
- only_dir: A boolean to restrict results to directories only.
- only_file: A boolean to restrict results to files only (this triggers a flat output structure).
- number_of_lines: The maximum number of lines to display in the output.
- depth: The maximum directory depth to traverse.
- using_a_filter: A boolean indicating if a filter is active (affects how zero-size files are handled).
- short_paths: A boolean to enable short path names, which may trigger parenthetical disambiguation if names collide.
```
pub struct AggregateData {
    pub min_size: Option<usize>,
    pub only_dir: bool,
    pub only_file: bool,
    pub number_of_lines: usize,
    pub depth: usize,
    pub using_a_filter: bool,
    pub short_paths: bool,
}
```
https://github.com/bootandy/dust/blob/master/src/filter.rs

Reference: Dust CLI flags and options

master

The following flags are available for the dust command line interface:

Flag	Description
`-p`	Show fullpath of the subdirectories
`-s`	Show apparent-size (file length) instead of disk space used
`-n <num>`	Show `<num>` directories instead of default terminal height
`-d <num>`	Show `<num>` levels of subdirectories
`-D`	Show only directories
`-F`	Show only files
`-r`	Reverse order of output
`-o <format>`	Output size in `si`, `b`, `kb`, `kib`, `mb`, `mib`, `gb`, or `gib`
`-X <name>`	Ignore all files/directories named `<name>`
`-x`	Only show directories on the same filesystem
`-b`	Do not show percentages or draw ASCII bars
`-B`	Move percent bars to the right side of the screen
`-i`	Do not show hidden files
`-c`	Monochrome (no colors)
`-C`	Force colors
`-f`	Count files (inodes) instead of disk space
`-t`	Group by filetype
`-z <size>`	Minimum size filter (e.g., `10M`, `30MB`, `20kib`)
`-e <regex>`	Only include files matching regex
`-v <regex>`	Exclude files matching regex
`-L`	Dereference links (treat symlinks as directories)
`-P`	Disable progress indicator
`-R`	Screen reader mode (removes bars/symbols, adds depth column)
`-S <size>`	Custom Stack size (use if encountering stack overflow)
`--skip-total`	Do not display the total row
`-j`	Print JSON representation (pipe to `jq`)
`--files0-from=FILE`	Read NUL-terminated file paths from FILE
`--files-from=FILE`	Read newline-terminated file paths from FILE
`--collapse=<name>`	Keep specific folder (e.g., `node-modules`) collapsed

Note: To include duplicate inodes when counting files, use dust -f -s.

dust

What's inside dust

Basic Usage

Common Tasks

Quick Install (Linux, macOS, Windows)

Package Managers

Manual Binary Installation