spacemap - Documentation
Description: Disk space analyzer with terminal visualizations and JSON export

# 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" }
      ]
    }

Note: The `disk_usage` field may be `null` if disk information cannot be retrieved.

## 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)