spacemap

Disk space analyzer with terminal visualizations

Installation

From crates.io

cargo install spacemap

From GitHub Releases

Download pre-built binaries from Releases.

Build from source

git clone https://github.com/chris-alexiuk/spacemap
cd spacemap
cargo build --release

Basic Usage

# Scan current directory
spacemap

# Scan specific path
spacemap /path/to/directory

# Show top 20 largest files and directories
spacemap --verbose --top 20

# Get help
spacemap --help

Categorization Modes

spacemap can categorize files in three different ways:

By file type (default)

spacemap --by type

Groups files by extension into categories like Images, Videos, Code, etc.

By size

spacemap --by size

Groups files into size buckets (0-1 KiB, 1-10 KiB, etc.).

By age

spacemap --by age

Groups files by last modification time (0-7 days, 7-30 days, etc.).

Options

Option	Description
--by <MODE>	Categorization mode: type, size, or age
-v, --verbose	Show top N files and directories
--top <N>	Number of top items to show (default: 10)
--max-depth <N>	Maximum recursion depth
--exclude <PATTERN>	Exclude paths containing pattern
--follow-symlinks	Follow symbolic links
--no-color	Disable colored output
--json	Output JSON to stdout
--output <FILE>	Write JSON output to file

Examples

Exclude directories

spacemap --exclude node_modules --exclude .git

Limit recursion depth

spacemap --max-depth 3

Custom size buckets

spacemap --by size --size-buckets "1024,10240,102400,1048576"

Comma-separated byte values for bucket boundaries.

Custom age buckets

spacemap --by age --age-buckets "1,7,30,90,365"

Comma-separated day values for age boundaries.

JSON export

# To stdout
spacemap --json

# To file
spacemap --output report.json

Output Format

Terminal output shows:

• Disk usage information
• Total files and directories scanned
• Category breakdown with size, percentage, and file count
• Visual bar chart of distribution
• Top N largest files (with --verbose)
• Top N largest directories (with --verbose)

File Type Categories

When using --by type, files are grouped into these categories:

• Images: jpg, png, gif, svg, webp, ico, heic, etc.
• Videos: mp4, avi, mkv, mov, webm, m4v, etc.
• Audio: mp3, wav, flac, aac, ogg, m4a, etc.
• Documents: pdf, doc, docx, txt, md, odt, etc.
• Spreadsheets: xls, xlsx, csv, ods
• Presentations: ppt, pptx, odp
• Archives: zip, tar, gz, 7z, rar, etc.
• Code: rs, py, js, ts, java, c, cpp, go, etc.
• Config: json, xml, yaml, toml, ini, etc.
• Binaries: exe, dll, so, bin, deb, rpm
• Disk Images: iso, img, dmg, vdi, vmdk
• Databases: db, sqlite, sql, mdb
• Logs: log
• Fonts: ttf, otf, woff, woff2
• Other: everything else

JSON Schema

When using --json or --output, the output follows this structure:

{
  "scanned_path": "string",
  "mode": "type|size|age",
  "totals": {
    "total_bytes": 0,
    "file_count": 0,
    "dir_count": 0,
    "skipped_paths": 0
  },
  "disk_usage": {
    "total_space": 0,
    "available_space": 0,
    "used_space": 0,
    "used_percent": 0.0
  },
  "buckets": [
    {
      "key": "string",
      "label": "string",
      "bytes": 0,
      "percent": 0.0,
      "file_count": 0
    }
  ],
  "top_files": [
    { "path": "string", "bytes": 0 }
  ],
  "top_dirs": [
    { "path": "string", "bytes": 0 }
  ],
  "warnings": [
    { "path": "string", "error": "string" }
  ]
}

Exit Codes

Code	Meaning
0	Success
1	Scan completed with warnings (some paths unreadable)
2	Invalid arguments
3	Runtime failure

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)