.\" Manual page for mapsize. View with: man -l docs/mapsize.1
.TH MAPSIZE 1 "October 2026" "mapsize 1.1.0" "User Commands"
.SH NAME
mapsize \- interactive terminal disk usage analyser with a navigable treemap
.SH SYNOPSIS
.B mapsize
[\fIOPTIONS\fR] [\fIPATH\fR]
.br
.B mapsize
[\fIOPTIONS\fR] \fISNAPSHOT\fR.msz
.br
.B mapsize
\fB\-\-compare\fR [\fIOPTIONS\fR] \fIOLD\fR.msz \fINEW\fR.msz
.br
.B mapsize
\fIPATH\fR {\fB\-\-top\fR \fIN\fR | \fB\-\-largest\-files\fR \fIN\fR | \fB\-\-json\fR | \fB\-\-csv\fR | \fB\-\-no\-ui\fR} [\fIOPTIONS\fR]
.SH DESCRIPTION
.B mapsize
scans a directory tree and shows its disk usage as a live, space-filling
treemap that fills the terminal. Each rectangle's area is proportional to the
size of a file or directory; colours show file categories. The display
populates while the scan runs and stays interactive throughout.
.PP
Arrow keys move spatially between rectangles, Enter shows details, Space
zooms into a directory and Backspace zooms out. Other views list directory
contents, file types, top-N lists, scan errors, duplicate files and snapshot
differences. A query language filters the treemap to matching data.
.PP
With no \fIPATH\fR the current directory is scanned. If \fIPATH\fR is a
snapshot file written by
.BR mapsize ,
it is opened instead of scanning. Options may appear before or after
positional arguments.
.PP
When any report option (\fB\-\-no\-ui\fR, \fB\-\-json\fR, \fB\-\-csv\fR,
\fB\-\-top\fR, \fB\-\-largest\-files\fR, \fB\-\-duplicates\fR) is given,
.B mapsize
runs non-interactively and writes to standard output, which makes it
suitable for scripts, cron jobs and SSH sessions without a full terminal.
Progress is written to standard error when it is a terminal.
.SH OPTIONS
.SS Scanning
.TP
.BI \-\-workers " MODE"
Number of concurrent directory readers:
.BR conservative " (2), " balanced " (default; min(8, 2\(mu CPUs)), " aggressive
(min(64, 8\(mu CPUs)), or a number from 1 to 1024. More is not always faster:
on rotational disks 2\(en4 workers are often best.
.TP
.BI \-\-follow\-symlinks " MODE"
.B none
(default) treats symbolic links as leaves.
.B same\-filesystem
follows links to directories on the same filesystem;
.B all
follows every directory link. Loops are detected and nothing is counted
twice. Ignored (forced to \fBnone\fR) on platforms without inode identity,
such as Windows.
.TP
.BR \-\-one\-file\-system ", " \-x
Do not descend into directories on a different filesystem than the scan
root. Without it, other filesystems are scanned (as
.BR du (1)
does) and marked as mount points; Linux virtual filesystems (proc, sysfs,
cgroup, debugfs, \&...) are never scanned.
.TP
.BI \-\-exclude " PATTERN"
Skip matching entries. A pattern containing a path separator matches the
absolute path (relative patterns are resolved against the working
directory) and everything beneath it; otherwise it is a shell glob matched
against the entry name. May be repeated. Exclusions are always shown in the
interface and reports.
.TP
.BI \-\-scan " PATH"
Path to scan; an alternative to the positional argument.
.SS Display
.TP
.B \-\-apparent
Size by logical (apparent) size instead of allocated disk usage.
.TP
.B \-\-si
Use SI units (kB, MB, GB; powers of 1000) instead of the default IEC units
(KiB, MiB, GiB; powers of 1024). The two are never mixed.
.TP
.BI \-\-theme " NAME"
Colour theme:
.BR default ", " dark ", " high\-contrast " or " mono .
.TP
.BI \-\-color " DEPTH"
Override colour detection:
.BR auto " (default), " truecolor ", " 256 ", " 16 " or " none .
Useful over SSH, where \fBCOLORTERM\fR is often not forwarded.
.TP
.B \-\-no\-mouse
Disable mouse support. Everything works from the keyboard.
.TP
.B \-\-read\-only
Disable every action that modifies the filesystem (moving to trash) and
show \fBREAD ONLY\fR in the header. Saving a snapshot file is still
allowed. This does not make
.B mapsize
a forensic acquisition tool: scanning uses ordinary filesystem calls, and
duplicate detection reads file contents, which may update access times.
.SS Reports
.TP
.B \-\-no\-ui
Scan without the interactive interface and print a summary.
.TP
.BI \-\-top " N"
Print the \fIN\fR largest entries directly under the root.
.TP
.BI \-\-largest\-files " N"
Print the \fIN\fR largest files anywhere in the tree.
.TP
.B \-\-json
Print the inventory as nested JSON, with scan metadata and error counts.
.TP
.B \-\-csv
Print one CSV row per entry: path, type, size, allocated, files, dirs,
errors, modified, flags. Paths are escaped so the output is safe to print
to a terminal.
.TP
.BI \-\-depth " N"
Limit \fB\-\-json\fR and \fB\-\-csv\fR to \fIN\fR levels (default \-1,
unlimited).
.TP
.B \-\-duplicates
Find files with identical content and print verified groups (see
\fBDUPLICATES\fR).
.SS Snapshots
.TP
.BI \-\-save " FILE" "\fR, \fP\-\-snapshot " FILE
Save a snapshot when the scan completes (not if it was cancelled).
.TP
.BI \-\-load " FILE"
Open a snapshot instead of scanning.
.TP
.B \-\-compare
Compare two snapshots given as positional arguments, \fIOLD\fR then
\fINEW\fR. Opens the interface (read-only) with growth and shrinkage
colouring, or prints the most significant changes with \fB\-\-no\-ui\fR
(\fB\-\-top\fR sets how many; default 30).
.SS Diagnostics
.TP
.BI \-\-log " FILE"
Append a log to \fIFILE\fR without disturbing the interface. Full paths are
logged only at \fBdebug\fR level and above.
.TP
.BI \-\-log\-level " LEVEL"
.BR error ", " warn ", " info " (default), " debug " or " trace .
.TP
.BI \-\-cpuprofile " FILE"
Write a Go CPU profile.
.TP
.BI \-\-memprofile " FILE"
Write a Go heap profile on exit.
.TP
.B \-\-version
Print the version and exit.
.TP
.BR \-h ", " \-\-help
Print usage and exit.
.SH KEYS
.SS Navigation
.TP 18
.BR "\(ua \(da \(<- \(->" ", " "h j k l"
Move to the neighbouring rectangle in that direction (lists: move the
cursor).
.TP
.B Enter
Show item information: path, logical and allocated size, type, category,
times, mode, owner, group, hard links, sparseness, and for directories file
and directory counts, share of parent and scan, largest child and errors
beneath.
.TP
.BR Space ", " \(->
Zoom into the selected directory (lists: enter it).
.TP
.BR Backspace ", " \(<-
Zoom out one level.
.TP
.B Home
Return to the scan root.
.TP
.B Esc
Clear the filter, otherwise zoom out; closes any open window.
.SS Views
.TP 18
.BR Tab ", " Shift+Tab
Next / previous view.
.TP
.BR 1 \(en 7
Jump to a view:
.BR Map ", " List ", " Types ", " Top ", " Scan ,
then \fBChanges\fR (compare mode) and \fBDups\fR (after a duplicate
search).
.TP
.B x
File types: count and size per extension. Enter filters the map by that
extension.
.TP
.B g
Top lists: largest files, largest directories by own files, oldest and
newest large files, directories with most entries, sparse files, hard-linked
files. \(<- and \(-> switch lists; Enter shows details; Space jumps to the item
in the map.
.TP
.B e
Scan information and the error list.
.TP
.B D
Find duplicate files (asks first).
.SS Actions
.TP 18
.B /
Search or filter (see \fBFILTER LANGUAGE\fR). Enter keeps the filter, Esc
clears it.
.TP
.B a
Toggle allocated / logical size.
.TP
.B c
Copy the selected path to the clipboard (OSC 52; terminal support varies).
.TP
.B o
Reveal the selected item in the desktop file manager.
.TP
.BR d ", " Delete
Move the selected item to the trash after confirmation. Disabled with
\fB\-\-read\-only\fR, for snapshots, and while scanning.
.TP
.B s
Save a snapshot.
.TP
.B r
Rescan, returning to the same directory when it is found again.
.TP
.B T
Cycle colour themes.
.TP
.BR ? ", " F1
Help.
.TP
.B Ctrl+C
Cancel a running scan; press again to quit.
.TP
.B q
Quit (in a window: close it).
.SS Mouse
Click selects a rectangle or row; double-click zooms into a directory or
shows file details; right-click shows details; the wheel zooms the map or
scrolls lists and windows. Clicking a breadcrumb or tab activates it.
Clicking outside a window closes it.
.SH DISPLAY
Directories are drawn with a border, their name on the top edge and their
size and share on the bottom edge; large directories show nested previews of
their contents. The selected rectangle has a double border and a highlighted
title, so it remains visible without colour.
.PP
A terminal has few cells, so entries too small to draw usefully are merged
into one hatched \fI"N smaller items"\fR block. Enter lists them; zooming in
or enlarging the terminal reveals them individually.
.PP
Layouts adapt to the terminal size: a side panel with a category breakdown
appears in large terminals, smaller ones get a compact layout, and below
40\(mu10 a short message is shown instead. Every resize recomputes the
layout for the new size while keeping the selection, zoom and filter.
.PP
Categories are: Image, Video, Audio, Archive, Disk image, Database, Source
code, Document, Executable, Log, Cache and Other. Directories take the colour
of the category using most of their space. In compare mode colours show
change instead: red grew, green shrank, blue new, grey unchanged.
.SH FILTER LANGUAGE
A query is one or more conditions combined with
.BR AND ,
.B OR
and
.B NOT
(also
.BR && ", " || ", " ! ),
with parentheses for grouping. Conditions written side by side are joined
with AND. Keywords and string comparisons are case-insensitive.
.PP
A bare word matches names containing it; a word with \fB*\fR, \fB?\fR or
\fB[\fR is a glob on the name. Otherwise a condition is
\fIfield operator value\fR:
.TP 12
.B Fields
.BR name ", " path ", " ext ", " type " (file, dir, symlink, other), " category ,
.BR size ", " allocated ", " age ", " modified ", " owner ", " group ,
.BR files " (entries beneath a directory), " flag
(sparse, hardlink, error, mount, incomplete, followed, broken).
.TP
.B Operators
.BR = ", " != ", " > ", " >= ", " < ", " <= ", " contains ", " matches
(regular expression; also \fB~\fR) and
.B in
with a parenthesised list: \fBext IN (iso,qcow2)\fR.
.TP
.B Sizes
.BR kB ", " MB ", " GB ", " TB
are SI (1000);
.BR KiB ", " MiB ", " GiB ", " TiB
are IEC (1024); bare
.BR K ", " M ", " G ", " T
follow the display units.
.TP
.B Ages
.BR s ", " min ", " h ", " d " (default), " w ", " mo " (30 days), " y
(365 days).
.B modified
also accepts dates such as 2024\-01\-31.
.PP
A matching directory contributes its whole contents. Examples:
.PP
.RS
.nf
ubuntu
*.iso
size > 5GB
size > 500MB AND ext IN (iso,qcow2,vmdk)
path contains cache AND NOT type = dir
age > 365d AND size > 100MiB
owner = andy OR flag = sparse
.fi
.RE
.SH SIZES
By default sizes are \fIallocated\fR (blocks actually used on disk, like
.BR du (1));
\fB\-\-apparent\fR or \fBa\fR switches to \fIlogical\fR size. Both appear in
the information window. Files whose allocated size is at least 4 KiB smaller
than their logical size are flagged sparse (this also covers filesystem
compression). On Windows allocated size is not available and logical size is
used.
.PP
Hard links: the first path seen for an inode is counted; later paths add
nothing to totals and are marked. Which path counts first depends on scan
order. Windows does not report link counts during enumeration, so hard links
are not deduplicated there.
.PP
Totals are marked incomplete whenever something could not be read
(permission denied, I/O error, files vanishing during the scan, a cancelled
scan). Every error is listed in the Scan view.
.SH DUPLICATES
Duplicate detection never relies on names or sizes alone. Files are grouped
by exact size, then three 16 KiB samples (start, middle, end) are hashed,
and remaining candidates are hashed completely with SHA-256. Only files with
identical SHA-256 digests are reported as duplicates. Hard links to the same
inode are not reported. Files that change size or cannot be read during the
search are skipped and counted.
.SH SNAPSHOTS
A snapshot stores the whole inventory in a versioned, gzip-compressed binary
format with a SHA-256 checksum; it reloads far faster than a rescan of a
large or slow filesystem. Snapshot files are treated as untrusted: corrupt
or malicious files are rejected, sizes are bounded, decompressed size is
limited to 64 times the file size, and aggregates are recomputed rather than
read. Comparison matches entries by path.
.SH FILES
.TP
.I $XDG_CONFIG_HOME/mapsize/config.json
Optional settings (default \fI~/.config/mapsize/config.json\fR on Linux,
\fI~/Library/Application Support/mapsize/config.json\fR on macOS,
\fI%AppData%\(rsmapsize\(rsconfig.json\fR on Windows). Command-line options
override it. Keys:
.BR workers ", " follow_symlinks ", " one_file_system ", " units " (iec or si), "
.BR size_mode " (allocated or logical), " theme ", " mouse ", " excludes " (list), "
.BR category_colors " and " extension_colors " (maps to \(dq#rrggbb\(dq), " refresh_hz .
.PP
.RS
.nf
{
  "workers": "balanced",
  "theme": "dark",
  "excludes": ["/proc", "*.tmp"],
  "extension_colors": {"qcow2": "#c678dd"}
}
.fi
.RE
.TP
.I ~/.local/share/Trash
Where \fBd\fR moves items on Linux (freedesktop.org trash; items on other
filesystems go to \fI.Trash\-UID\fR at that filesystem's top). macOS uses
\fI~/.Trash\fR; Windows uses the Recycle Bin.
.SH ENVIRONMENT
.TP
.B NO_COLOR
If set, use the \fBmono\fR theme (attributes and glyphs only).
.TP
.BR COLORTERM ", " TERM
Used for colour detection. On \fBTERM=linux\fR box drawing falls back to
ASCII.
.TP
.B MAPSIZE_ASCII
If set, draw with ASCII characters only.
.TP
.B MAPSIZE_DEBUG_PANIC
Developer aid: \fBui\fR or \fBscanner\fR deliberately crashes to verify that
the terminal is restored.
.SH EXIT STATUS
.TP
.B 0
Success, including a scan cancelled from the interface.
.TP
.B 1
An error occurred (for example the path does not exist, a snapshot is
invalid, or an internal error).
.TP
.B 2
Invalid command-line usage.
.SH EXAMPLES
.TP
.B mapsize /srv
Explore /srv interactively.
.TP
.B mapsize \-x /
Explore the root filesystem without crossing into other mounts.
.TP
.B mapsize \-\-read\-only \-\-color 256 /mnt/evidence
Investigate without any modifying actions, forcing 256 colours.
.TP
.B mapsize /srv \-\-no\-ui \-\-save srv\-$(date +%F).msz
Nightly snapshot from cron.
.TP
.B mapsize \-\-compare srv\-2026\-10\-01.msz srv\-2026\-10\-02.msz
See what grew overnight.
.TP
.B mapsize /home \-\-top 20 \-\-exclude \(aq*.tmp\(aq
Print the 20 largest entries under /home.
.TP
.B mapsize /data \-\-json \-\-depth 2 | jq .tree.children[0]
Machine-readable output.
.SH SECURITY
Filenames are untrusted. Control characters, escape sequences, bidirectional
overrides and invalid UTF-8 in names are displayed in escaped form (for
example \fB\(rsx1b\fR) and are never sent to the terminal; the real names are
kept for file operations. No shell is ever invoked: opening the file manager
and moving to the trash use direct program execution or native APIs.
.SH BUGS
Trash and file-manager integration have been tested on Linux only. Hard-link
deduplication, allocated sizes and symlink following are unavailable on
Windows. Keybindings are not configurable.
.PP
Report bugs to the author.
.SH AUTHOR
Andy Dixon <mapsize@dixon.cx>
.br
https://dixon.cx
.SH SEE ALSO
.BR du (1),
.BR df (1),
.BR ncdu (1),
.BR find (1)