Leaves – Text‑UI Disk Usage Treemap Visualizer

Leaves – Text‑UI Disk Usage Treemap Visualizer

Leaves provides a terminal‑based treemap view of disk usage

Leaves visualizes files and directories as nested rectangles whose area is proportional to size, similar to WinDirStat but runs entirely in a text UI. This makes it practical for remote shell sessions where graphical applications cannot be used.

Core functionality: size‑proportional rectangles

Leaves scans a target directory and draws a hierarchy of rectangles. Each rectangle’s area reflects the file or directory’s disk usage, so a 200 MiB file appears twice as large as a 100 MiB sibling. Directories are shown as collections of their children, allowing quick visual comparison of sub‑trees.

"The area of a rectangle is proportional to its size. A 200 MB file will have twice the size as a sibling with 100 MB."

Because the UI works at the character level, the approximation is coarse compared to graphical tools, but it remains highly informative for quick assessments.

Getting started: binaries and build options

Pre‑built binaries

Leaves offers pre‑compiled releases for several platforms on its GitHub releases page. If a binary for your OS is unavailable, you can build from source.

Building from source

  1. Install Rust – the project requires a Rust toolchain. The recommended method is rustup:

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

    Ensure you also have basic build tools (gcc, make, etc.) installed via your distro’s development package group.

  2. Alternative with Nix – if you prefer reproducible builds, install Nix and enter a development shell:

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

  3. Compile – run Cargo to build a release binary:

    cargo build --release

    You can also install the binary for the current user with:

    cargo install --path .

Running Leaves

Execute the binary with a directory argument, or omit the argument to scan the current working directory:

leaves ~/Documents

Leaves respects ignore files by default:

  • Hidden files/directories are skipped.
  • Patterns from .gitignore, .ignore, and .git/info/exclude are excluded.

Use -A to disable all automatic ignore rules, or combine selective flags (-H, -I, -G, -E). Globs (including negated ! globs) can be supplied to refine the scan.

User interface layout

Normal view

The main screen consists of:

  • Title bar – shows the current path, total size, and file count.
  • Sidebar – a collapsible explorer tree; navigation keys are ↑ ↓ ← →, and Space toggles directory expansion.
  • Central panel – the treemap of rectangles.
  • Bottom bar – shortcut hints for actions.

Color scheme

  • Files are colored by extension using a warm palette (yellow/orange/brown).
  • Directories receive a cooler viridis‑style palette (blues/greens).
  • Set LEAVES_COLORS=swap to exchange the palettes.

Interaction patterns

Focus view

Press Enter on a selected directory to focus it, replacing the explorer and treemap with that subtree. Press Backspace to return to the parent. Navigation is confined to the initial target directory.

Expansion / deflation

Because block characters limit visual granularity, Leaves summarizes deep hierarchies. Use:

  • e – expand the selected directory (rescans up to the runtime depth).
  • d – deflate the directory, collapsing children into file‑type summary rectangles.
  • + / - – adjust the runtime depth limit.

X‑ray mode

Press x to toggle x‑ray mode, which groups top‑level rectangles by file type before subdividing by directory. This helps mitigate the character‑resolution limitation for directories with many small files.

Configuration and theming

Leaves reads a TOML configuration file from $XDG_CONFIG_HOME/leaves/settings.toml (typically ~/.config/leaves/settings.toml). Most settings can also be overridden with LEAVES_ environment variables.

Setting Values Description Env var
dark_mode true / false Switches to a light‑on‑dark theme for dark terminals. LEAVES_DARK_MODE
color_shift 0.0 – 1.0 Lightens or darkens colors for better visibility. LEAVES_COLOR_SHIFT
colors theme name Selects a built‑in or custom color theme. LEAVES_COLORS
dir_style thick / plain Controls border thickness for directories. LEAVES_DIR_STYLE

Four built‑in themes are provided: fall, spring, greys, and mono. Custom themes can be defined under themes.YOUR_THEME with dirs and files arrays of HTML color codes.

Practical considerations

  • Memory usage – Leaves keeps the tree up to a configurable depth in memory. Setting --max-depth higher loads more detail but increases RAM consumption.
  • Root scans – When scanning /, exclude virtual filesystems (/proc, /sys, /dev, etc.) using negative overrides, e.g.:
    leaves -A -d 3 / '!/proc' '!/tmp' '!/run' '!/sys' '!/dev' '!/mnt' '!/nix'
  • Symlinks – Leaves does not follow symbolic links, avoiding double‑counting of disk usage. Hard links are counted multiple times because detection is not implemented.

Community reaction

The Hacker News discussion highlighted several points:

"I’ve always used ncdu for this kind of thing but I like this a lot better." – ktm5j

"A windirstat‑like tool for Linux was exactly what I was looking for." – rrauenza

"Being able to brew‑install this on macOS would be killer." – sghiassy

"The file‑type partitioning feature is a smart addition to handle block‑character limitations." – takencoder

These comments underscore Leaves’ appeal as a lightweight, TUI alternative to GUI disk‑usage visualizers such as WinDirStat, SpaceSniffer, or WizTree.

When to choose Leaves over other tools

  • Remote environments – No X server required; works over SSH.
  • Quick visual overview – Treemap gives an at‑a‑glance sense of large directories.
  • Customizable colors and themes – Adjust to fit terminal color schemes.
  • Extensible ignore handling – Leverages existing .gitignore and .ignore files.

If you need a full‑featured GUI with pixel‑perfect precision, a graphical tool may still be preferable. For fast, terminal‑centric inspection, Leaves fills a niche that tools like ncdu, dua-cli, or mcdu do not address.

Getting Leaves

# Install via Cargo (requires Rust)
cargo install --git https://github.com/patonw/leaves.git

Or download a pre‑built binary from the GitHub releases page.

Leaves demonstrates how a classic visual metaphor—treemaps—can be adapted to the constraints of a text UI, delivering a useful disk‑usage analysis tool for developers and sysadmins working in headless environments.

Sources