mapsize/README.md

mapsize

An interactive, full-terminal disk usage analyser built around a live, navigable treemap. Think WinDirStat + ncdu + WizTree, in one Go binary that runs over SSH.

mapsize is a working name; branding lives in internal/brand.

Status

Version 1.0. See CHANGELOG.md, ROADMAP.md for what comes next, and PERFORMANCE.md for measured numbers. Tested on Linux; macOS and Windows builds are produced but trash and file-manager integration have not yet been tested there.

What it does

• Live treemap. A squarified, space-filling treemap fills the terminal and grows while the scan runs. Directories show nested previews of their contents; colours are file categories (video, archives, disk images, code, …). Items too small to draw collapse into a "N smaller items" block until you zoom in.
• Spatial navigation. Arrow keys move to the block that is actually to the left/right/above/below. Enter inspects, Space zooms in, Backspace zooms out, Home returns to the root. The selection survives rescans, resizes and filtering.
• Resizes properly. Every resize recomputes the layout for the new geometry (it never stretches the old one); large terminals get a side panel, small ones a compact layout, tiny ones a polite message.
• Search and filter with a small query language — the treemap shows only matching data: ubuntu · *.iso · size > 5GB · ext IN (iso,qcow2,vmdk) · age > 365d · path contains cache AND NOT type = dir · owner = andy
• Investigation views (Tab): directory list, file types, top lists (largest files/dirs, oldest/newest large files, most entries, sparse and hard-linked files), scan information with every error, duplicates.
• Honest numbers. Allocated vs logical size, hard links counted once, sparse files flagged, permission errors and skipped areas always shown; incomplete totals are labelled as such.
• Snapshots: save a scan, reopen it instantly, compare two — the treemap colours growth and shrinkage.
• Safe with hostile filenames: control characters and escape sequences in names are displayed escaped and never reach the terminal.

Keys

Key	Action
↑ ↓ ← → / hjkl	move spatially through the map
Enter	item information
Space / →	zoom into directory
Backspace / ←	zoom out
Home	scan root
/	search / filter (Esc clears)
Tab, Shift+Tab, 1–7	switch views
x, g, e	file types, top lists, scan info & errors
D	find duplicates
a	toggle allocated / logical size
c, o	copy path, reveal in file manager (headless: show the folder in the map)
d	move to trash, or delete permanently when headless (asks; disabled with --read-only)
s, r	save snapshot, rescan
T	cycle theme
?	help
Ctrl+C	cancel scan, then quit
q	quit

Mouse: click selects, double-click zooms, right-click inspects, wheel zooms the map or scrolls lists. Everything works without a mouse (--no-mouse).

Install

go install github.com/andydixon/mapsize/cmd/mapsize@v1.0.0
# or
make build   # → bin/mapsize
sudo make install   # binary + man page under /usr/local (PREFIX=… to change)

# Homebrew (macOS and Linux)
brew install andydixon/tap/mapsize

On Debian, Ubuntu, Fedora, RHEL, openSUSE and Arch, mapsize is also in the signed apt, dnf and pacman repository at repo.dixon.cx, so it updates with the rest of the system: see https://dixon.cx/repo for the setup commands.

Full reference: man mapsize after installing, or make man / man -l docs/mapsize.1 from the source tree.

Usage

mapsize .                       # scan and explore interactively
mapsize --read-only /mnt/evidence
mapsize /srv --save srv.msz     # explore, and save a snapshot when done
mapsize srv.msz                 # reopen a snapshot (no rescan)
mapsize --compare old.msz new.msz

# non-interactive
mapsize /srv --top 50
mapsize /srv --largest-files 20
mapsize /srv --json --depth 3
mapsize /srv --csv > inventory.csv
mapsize /srv --no-ui --save snapshot.msz
mapsize /srv --duplicates --no-ui

Sizes and units

• By default sizes are allocated (disk usage, like du); --apparent switches to logical size. Both are shown in the info modal.
• Units are IEC (KiB, MiB, GiB — powers of 1024) everywhere; --si switches everything to SI (kB, MB, GB — powers of 1000). Never mixed.
• Hard links are counted once (first path seen); see ARCHITECTURE.md.

Filesystem boundaries and exclusions

• Default: other filesystems are descended (like du), except Linux virtual filesystems (proc, sysfs, cgroup, …) which are never scanned. Mount points are marked.
• --one-file-system / -x: stay on the root's filesystem.
• --follow-symlinks=none|same-filesystem|all (default none). Loops are detected and nothing is counted twice.
• --exclude PATTERN (repeatable): glob on entry name, or a path prefix if the pattern contains a separator. Exclusions are always shown in the UI.

Configuration

Optional JSON file at $XDG_CONFIG_HOME/mapsize/config.json (macOS: ~/Library/Application Support/mapsize/config.json, Windows: %AppData%\mapsize\config.json):

{
  "workers": "balanced",
  "theme": "default",
  "units": "iec",
  "excludes": ["/proc", "*.tmp"],
  "category_colors": {"Video": "#e06c75"},
  "extension_colors": {"qcow2": "#c678dd"}
}

Colour

Colour support is auto-detected; --color truecolor|256|16|none overrides it (handy over SSH, where COLORTERM is often not forwarded). Themes: default, dark, high-contrast, mono (--theme, or T to cycle). NO_COLOR is respected. On the Linux console, or with MAPSIZE_ASCII=1, box drawing falls back to ASCII.

Read-only mode

--read-only disables every modifying action and shows READ ONLY in the header. (Saving a snapshot file is still allowed; it writes only where you tell it to.) It does not make mapsize a forensic acquisition tool: scanning uses ordinary filesystem APIs, and duplicate detection reads file content (which may update access times).

Deletion

d moves the selected item to the system trash (freedesktop.org trash on Linux, ~/.Trash on macOS, the Recycle Bin on Windows) after confirmation, using native file operations — never a shell.

On a headless Linux or BSD system (neither DISPLAY nor WAYLAND_DISPLAY set) nothing ever empties the trash, so trashing would not free any space. There d deletes permanently instead, after a confirmation that says it cannot be undone, and o shows the folder in the map rather than opening a file manager.

Deletion is unavailable while scanning, for snapshots, and in read-only mode.

Documentation

• docs/mapsize.1 — manual page
• ARCHITECTURE.md — design and invariants
• DEVELOPMENT.md — building, testing, profiling
• PERFORMANCE.md — measured results

License

GPL-3.0-or-later. See LICENSE.