🍃 Leaves: A TUI Disk Usage Treemap Visualizer

Leaves is a terminal-based utility designed to analyze disk space, drawing inspiration from graphical tools like QDirStat and WinDirStat. Instead of a standard list, it represents your filesystem as a series of nested rectangles.

📐 How it Works

The application maps directory structures to a visual treemap. The spatial area of a rectangle is intended to be proportional to the size of the file or folder it represents.

$\text{Area} \approx \text{Disk Usage}$

For example, if you have a 200 MB file and a 100 MB sibling, the larger file will occupy roughly twice the space. A parent directory containing both would be approximately three times the size of the smaller file.

[!IMPORTANT] Because this is a ~~graphical~~ text-mode tool, the resolution is limited by character dimensions. This results in a coarser approximation than a GUI, but it allows the tool to function perfectly over remote SSH connections where a desktop environment is unavailable.

🚀 Getting Started

You can acquire a pre-compiled binary via the releases page. If your platform isn't supported, you can build it from the source code.

🛠️ Setup Checklist

Install Rust toolchain
Install build essentials (gcc, make, ld, etc.)
Clone the repository
Compile the binary

Installation Options

Option 1: Using `rustup`

The recommended method for installing Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Option 2: Using `nix`

For those preferring a declarative environment:

curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install | sh -s -- --daemon

Once installed, enter the project environment with:

cd leaves
nix-shell

🏗️ Build and Install

To compile the project for production:

cargo build --release

To install the binary for the current user:

cargo install --path .

Note: Ensure your system's PATH is configured to recognize the cargo installation directory.

💻 Execution & Usage

Running the App

If you haven't installed it globally, run it via cargo: cargo run --release -- [flags] /path/to/dir

To use the installed binary: leaves ~/Documents

Default Behavior:

If no path is provided, it scans the current directory.
It automatically ignores files matching patterns in .gitignore or .ignore files.
You can provide specific globs (use ! to negate a pattern).

Command Line Options

Flag	Long Form	Description	Default
`-d`	`--max-depth`	Max tree depth kept in memory	`5`
`-x`	`--xray`	Group by type at top-level, then by directory	N/A
`-A`	`--include-all`	Disable automatic skipping of files	N/A
`-H`	`--include-hidden`	Show hidden files/folders	N/A
`-I`	`--include-ignored`	Include `.ignore` files	N/A
`-G`	`--include-gitignored`	Include `.gitignore` files	N/A
`-E`	`--include-gitexcluded`	Include `.git/info/exclude` files	N/A
`-h`	`--help`	Display help menu	N/A
`-V`	`--version`	Show version number	N/A

🎨 Interface & Navigation

Layout Components

Title Bar: Displays the current path, total size, and total file count.
Detail Box: Located below the tree, showing specific metadata for the selected item.
Central Panel: The treemap visualization.

Visual Logic

Files: Colored by extension using a yellow $\rightarrow$ orange $\rightarrow$ brown palette.
Directories: Colored by name using the viridis palette (mostly blues and greens).
Sizing: Because borders require a minimum of two characters, deeply nested items may appear slightly smaller than top-level items of the same size.

Pro Tip: You can invert the color schemes by setting the environment variable LEAVES_COLORS=swap. While both palettes use yellow, directory colors are generally more vibrant.

Interaction

Mouse Support: Click to select files or folders.
Synchronization: The explorer tree and the treemap are bidirectionally linked.
Highlighting: Selected items and their parent chain are marked with thicker borders.
Drill-down: Press Enter to focus on a directory. This updates both the tree and the map.
Navigation: You can move back up the hierarchy, but you cannot navigate above the original root directory used at launch.