Metadata-Version: 2.4
Name: flamedisk
Version: 1.2.1
Summary: Flame-graph & treemap disk-usage visualiser
Author-email: Jon Vannucci <JRVannucci@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/jrvannucci/flamedisk
Project-URL: Repository, https://github.com/jrvannucci/flamedisk
Project-URL: Changelog, https://github.com/jrvannucci/flamedisk/blob/main/CHANGELOG.md
Keywords: disk,usage,flamegraph,treemap,storage,du
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Dynamic: license-file

# flamedisk 🔥

Interactive disk-usage visualiser. Scan a directory and open a self-contained HTML report with a flame graph and sortable file tree — no server required.

![Tree + Flame view](https://raw.githubusercontent.com/jrvannucci/flamedisk/main/docs/img/tree-flame-view.png)

---

## Install

```
pip install flamedisk
```

Requires Python 3.9+. No runtime dependencies beyond the standard library.

## Quick start

```
flamedisk /path/to/scan
```

The report opens in your default browser. The HTML file is fully self-contained — share it as a single file, no internet connection needed.

## CLI

```
flamedisk [path] [options]
```

| Option | Default | Description |
|---|---|---|
| `path` | `.` | Directory to scan |
| `-o FILE` / `--output FILE` | temp file | Write HTML to a specific path |
| `--depth N` | unlimited | Maximum scan depth |
| `--min-size BYTES` | `0` | Skip files smaller than this (e.g. `1MB`, `512KB`) |
| `--exclude NAME …` | — | Names or glob patterns to skip (e.g. `.git node_modules '*.log'`) |
| `--follow-symlinks` | off | Follow symbolic links (cycles are detected and skipped) |
| `--actual-size` | off | Measure allocated disk blocks instead of apparent size, like `du` (Unix only) |
| `-x` / `--one-file-system` | off | Skip directories on a different filesystem, like `du -x` |
| `--dedup-links` | off | Count hard-linked files only once, like `du` |
| `--workers N` | auto | Thread-pool size. Auto = `cpu_count × 4`, max 32 |
| `-q` / `--no-browser` | off | Skip opening a browser window |
| `--json` | off | Print raw JSON tree to stdout instead of HTML |
| `--title TEXT` | — | Custom HTML page title |
| `--version` | — | Print version and exit |

### Examples

```bash
# Scan home directory and open in browser
flamedisk ~

# Save report without opening browser
flamedisk /var/log -o report.html -q

# Limit depth, skip small files
flamedisk /usr --depth 4 --min-size 1MB

# Skip virtual filesystems
flamedisk / --exclude proc sys dev -q

# Skip files by glob pattern (quote so the shell doesn't expand them)
flamedisk . --exclude '*.log' '*.tmp'

# Path with spaces
flamedisk "/home/My Documents"

# Exclude list followed by a spaced path
flamedisk --exclude .git node_modules -- "/my project"

# Pipe JSON tree to jq
flamedisk . --json | jq '.children[0]'
```

## Python API

```python
from flamedisk import scan, write_html

tree = scan(
    "/home/user",
    max_depth=5,
    exclude=[".git", "node_modules"],
    workers=16,
)
write_html(tree, "report.html")
```

See [docs/api.md](docs/api.md) for the full API reference.

## The report

### Tree + Flame view (default)

The left panel shows an expandable file tree. The right panel shows a flame graph — each row is a depth level, each cell is a file or directory sized proportionally to disk usage. The root sits at the bottom; deeper entries grow upward.

![Tree + Flame view](https://raw.githubusercontent.com/jrvannucci/flamedisk/main/docs/img/tree-flame-view.png)

### Flame view

The flame graph fills the full window.

![Flame view](https://raw.githubusercontent.com/jrvannucci/flamedisk/main/docs/img/flame-view.png)

### Zoom

Click any directory cell in the flame graph to zoom into it. The original colours and depth levels are preserved — the view rescales so the selected directory fills the full width. Press **Esc** or click **↺ Reset** to return.

![Zoom and tooltip](https://raw.githubusercontent.com/jrvannucci/flamedisk/main/docs/img/zoom-tooltip.png)

### List view

Flat sortable list of the current directory's immediate children. Sort by **Name**, **Size**, or **Type**. The size bar and percentage column always show each entry's share of the total root directory.

![List view](https://raw.githubusercontent.com/jrvannucci/flamedisk/main/docs/img/list-view.png)

### Search

Type in the search box (top-right) to highlight matching entries across all views. Matching cells are highlighted; non-matching entries are dimmed.

### Unreadable entries

If an entry can't be read during the scan — permission denied, a directory that vanished mid-scan, a stale network handle — flamedisk records it and keeps going rather than aborting. A ⚠ banner in the header shows how many entries were skipped; hover it for the full path and OS error of each. Affected rows in the tree carry a ⚠ marker, and selecting one shows the error in the status bar. Because the contents of a skipped entry are never counted, the totals shown understate actual disk usage by that amount.

### Keyboard shortcuts

| Key | Action |
|---|---|
| `Esc` | Clear zoom / exit search |

## Install from source

```bash
git clone https://github.com/jrvannucci/flamedisk
cd flamedisk
pip install -e ".[dev]"
```

## Development

```bash
pytest              # run the test suite
ruff check .        # lint
```

Tests run on Linux, macOS, and Windows across Python 3.9–3.13 in CI. Symlink
tests skip automatically where the environment cannot create symlinks (Windows
without Developer Mode).

## License

MIT
