Andy Dixon
8d9344cfef
On a headless Linux or BSD system (no DISPLAY or WAYLAND_DISPLAY) nothing empties the freedesktop trash, so trashing never freed space. There, d now deletes permanently after an explicit confirmation, checking owner and type against the scan and removing through an os.Root on the parent so a swapped symlink cannot redirect it. o shows the folder in the map instead of launching a file manager. Desktop sessions, macOS and Windows are unchanged.
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.
mapsizeis a working name; branding lives ininternal/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);--apparentswitches to logical size. Both are shown in the info modal. - Units are IEC (KiB, MiB, GiB — powers of 1024) everywhere;
--siswitches 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(defaultnone). 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.