Metadata-Version: 2.4
Name: treemap-cli
Version: 0.1.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Requires-Dist: pytest>=7 ; extra == 'test'
Provides-Extra: test
License-File: LICENSE
Summary: Fast disk usage analyzer: reads the NTFS Master File Table directly (like WizTree), with squarified treemaps
Keywords: disk usage,ntfs,mft,treemap,wiztree,du
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# treemap-cli

Fast disk usage analysis from Rust or Python. On Windows NTFS drives it reads the
**Master File Table directly from the raw volume** (the technique WizTree uses), so a
whole drive is scanned in seconds instead of minutes. Everywhere else it falls back to
a parallel directory walk. Results can be queried, exported (WizTree-style CSV, JSON)
or rendered as a squarified treemap (SVG, or raw tiles for your own renderer).

```
pip install treemap-cli
```

No Rust toolchain needed: PyPI has prebuilt wheels for Windows (x64, arm64), Linux
(x86_64, aarch64, musl) and macOS (arm64, x86_64), each covering Python 3.9+. Prefer no
Python at all? Download the standalone `treemap` binary for your platform from the
[GitHub Releases](https://github.com/Dbrown411/treemap-cli/releases) page (static
single-file executables, ~1 MB).

Rough timings for a full-drive scan (Administrator, MFT method):

| Drive | Entries | Time |
| --- | --- | --- |
| SATA SSD, ~3.7 GiB MFT | ~3 M files | ~14 s (bound by disk read speed) |
| NVMe SSD, ~0.7 GiB MFT | ~0.6 M files | ~1.3 s |
| ~3 M-record MFT re-parsed from a dump file | ~3 M files | ~3 s |

## Command line

```console
> treemap scan C:\demo -n 5 --largest 3 --extensions 3
24 files, 19 folders scanned in 14.86s via mft
   16.4 GiB    16.4 GiB  C:\demo
    3.9 GiB     3.9 GiB  #####                 23.9%  Videos\
    3.1 GiB     3.1 GiB  ####                  19.1%  backup.vhdx
    3.1 GiB     3.1 GiB  ####                  18.8%  Games\
    2.2 GiB     2.2 GiB  ###                   13.3%  Downloads\
    1.7 GiB     1.7 GiB  ##                    10.6%  Photos\
                        ... 4 more

Largest files:
    3.1 GiB  C:\demo\backup.vhdx
    2.5 GiB  C:\demo\Games\SpaceSim\data.pak
    1.9 GiB  C:\demo\Videos\holiday-2025.mp4

Largest extensions:
    3.1 GiB         1 files  .vhdx
    2.6 GiB         3 files  .mp4
    2.5 GiB         1 files  .pak
> treemap scan C:\Users --depth 2 --svg users.svg --csv users.csv
> treemap scan ~/src --method walk          # any OS / filesystem
> treemap dump-mft D: d.mft                 # snapshot the raw MFT ...
> treemap load-mft d.mft --root D:\         # ... and analyse it anywhere, later
```

## Interactive browser

```console
> treemap ui C:                 # scan, then browse
> treemap load-mft d.mft --ui   # browse a saved MFT dump
```

```
 treemap  C:\demo
 16.4 GiB size · 16.4 GiB allocated · 24 files · 19 folders · 100.0% of scan · mft in 14.35s
┌ Folder ─────────────────────────────────────────── by Size ┐┌ Treemap ───────────────────────────────────────────────────┐
│Size       Share               Files    Modified   Name     ││▀▀▀▀▀▀▀▀▀▀▀▀▀▀backup.vhdx Games      Downloads     Projects │
│3.9 GiB    ██▉           23.9% 4        2026/10/15 Videos\  ││▌Videos      ▐                                              │
│3.1 GiB    ██▎           19.1%          2026/10/15 backup.vh││▌            ▐                                              │
│3.1 GiB    ██▎           18.8% 3        2026/10/15 Games\   ││▌            ▐                                              │
│2.2 GiB    █▋            13.3% 3        2026/10/15 Downloads││▌            ▐                                              │
│1.7 GiB    █▎            10.6% 3        2026/10/15 Photos\  ││▌            ▐                       Photos                 │
│1.7 GiB    █▎            10.2% 4        2026/10/15 Projects\││▌            ▐                                              │
│615.0 MiB  ▌              3.7% 2        2026/10/15 Music\   ││▌            ▐                                     Music    │
│82.0 MiB                  0.5% 3        2026/10/15 Documents││▌            ▐                                              │
│12.0 KiB                  0.0%          2026/10/15 notes.txt││▄▄▄▄▄▄▄▄▄▄▄▄▄▄                                              │
└────────────────────────────────────────────────────────────┘└────────────────────────────────────────────────────────────┘
↑↓ move  Enter open  ⌫ up  Tab view  s sort  a size/alloc  t treemap  o reveal  ? help  q quit
```

A sortable folder table beside a colour treemap of the current folder (each top-level
entry gets a hue; nested folders are shaded within it). Keys: arrows / `hjkl` to move and
drill in/out, `Tab` or `1` `2` `3` to switch between folder, largest-files and extension
views, `s` to change the sort, `a` to measure allocated bytes instead of size, `t` to hide
the treemap, `o` to reveal the selection in Explorer/Finder, `r` to rescan, `?` for help.
The mouse works too: click a tile or row to select it, click it again (or double-click) to
open it, right-click to go up. (The examples above use a demo folder of placeholder files.
Scanning a folder via the MFT reads the whole volume's MFT, hence the time.)

From Python: `tm.ui("C:")`, or `scan.ui()` to browse a scan you already have.

The CLI is also available as a standalone Rust binary (`cargo install --path crates/treemap-cli`).

## Python

```python
import treemap_cli as tm

scan = tm.scan("C:")                    # method="auto" | "mft" | "walk"
print(scan)                             # <Scan "C:\\" 1204311 files, 230118 dirs, 210.4 GiB via mft in 6.1s>

for e in scan.root.children()[:10]:     # largest first
    print(f"{tm.human_bytes(e.size):>10}  {e.name}")

users = scan["C:\\Users"]               # case-insensitive lookup
scan.largest_files(20, under="C:\\Users")
scan.extensions(10)                     # [{'extension': 'dll', 'size': ..., 'files': ...}, ...]

# squarified treemap tiles for your own renderer: (entry, x, y, w, h, depth)
tiles = scan.treemap(1920, 1080, max_depth=3)

scan.to_svg("c.svg", 1920, 1080)
scan.to_csv("c.csv")                    # WizTree column layout
import pandas as pd
df = pd.DataFrame(scan.rows(), columns=["path", "size", "allocated", "modified", "is_dir", "files", "dirs"])
```

Scans release the GIL; the result is an immutable Rust tree, so `Entry` objects are
cheap views and millions of entries do not become millions of Python objects until you ask.

## How it works

1. `FSCTL_GET_NTFS_VOLUME_DATA` on `\\.\C:` gives cluster size, record size and the
   valid length of the MFT; `FSCTL_GET_RETRIEVAL_POINTERS` on `C:\$MFT` gives its
   physical extents (falling back to decoding record 0's own runlist).
2. The extents are read with unbuffered (`FILE_FLAG_NO_BUFFERING`) sequential I/O,
   several requests in flight, while a rayon pool applies update-sequence fixups and
   parses records in parallel.
3. Per record: `$STANDARD_INFORMATION` (mtime, attributes), `$FILE_NAME` (parent +
   name, skipping DOS 8.3 aliases; several names = hard links), `$DATA` (unnamed stream
   size; every stream's allocated clusters) and `$INDEX_ALLOCATION`. Extension records
   are merged into their base record.
4. Parent references link records into a tree; sizes roll up bottom-up.

Reading the raw volume needs **Administrator** rights. Without them (or on non-NTFS
volumes, network shares, Linux, macOS) `method="auto"` walks directories in parallel
instead and reports why in `scan.fallback_reason`.

### Size semantics

* **size** – logical length of the unnamed data stream (what Explorer shows).
* **allocated** – clusters actually in use × cluster size, over all streams (alternate
  data streams, `WofCompressedData`, …). Sparse and compressed files count only their
  real clusters; files small enough to live inside the MFT record count 0.
* **Hard links** are counted once by default, so totals match the space really used on
  disk. Pass `hardlinks="each"` / `--hardlinks each` to count every link (WizTree's and
  Explorer's behaviour).
* Directory index blocks (`$INDEX_ALLOCATION`) are included in a folder's allocated size.

Verified on a live C: drive: total allocated was within 0.15% of the volume's used
space reported by Windows.

## Development

```console
uv venv && uv pip install maturin pytest
maturin develop --release
pytest
cargo test --workspace
```

Release: push a `v*` tag; `.github/workflows/release.yml` builds abi3 wheels for
Windows (x64, arm64), Linux (x86_64, aarch64, musl) and macOS (arm64, x86_64), plus an
sdist, and publishes them with PyPI trusted publishing.

## Notes

The NTFS parsing is implemented from public NTFS documentation.

