Metadata-Version: 2.4
Name: diskface
Version: 1.1.0
Summary: disk usage analyzer with live sorted results
License-Expression: MIT
Project-URL: Homepage, https://github.com/harryeffinpotter/diskface
Keywords: disk,usage,analyzer,cli
Classifier: Environment :: Console
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: rich>=13.0

# diskface

A command-line disk & file usage analyzer with live, sorted results. It walks a
directory (the current one by default), sizes every folder du-style, and drops
you into an **interactive folder browser** — arrow keys to move, space to expand
into a folder, `d` to delete it (confirmed, sizes re-roll up live). Think `ncdu`,
but with diskface's junk-exclusion defaults. Progress and static output are
rendered with [rich](https://github.com/Textualize/rich); the browser is plain
stdlib curses, so there are no extra dependencies.

By default it scans **from the directory you're in**, sizes folders
**recursively** (a folder's size includes everything under it), and skips the
regenerable "app junk" that clutters a real answer — `node_modules`, `.git`,
`.cache`, `__pycache__`, virtualenvs, package caches, and so on. Only folders at
or above your **minimum size** are shown.

---

## Install

**From PyPI (any OS):**
```bash
pip install diskface        # or: pipx install diskface
```

**Arch Linux (AUR):**
```bash
yay -S diskface             # or your AUR helper of choice
```

Both give you a `diskface` command. The only runtime dependency is `rich`.

---

## First run

On first launch in a terminal, diskface runs a short setup wizard and writes your
answers to `~/.config/diskface/config.json`. Just press enter to take the
recommended default for each question. Re-run it any time with:

```bash
diskface --setup
```

To skip the wizard entirely (e.g. in scripts) and take defaults, pass `--yes`.

---

## Usage

```bash
diskface [options]
```

| Flag | Description |
| --- | --- |
| `-m`, `--min-size <MB>` | Minimum size for a folder/file to even show (default 100) |
| `-t`, `--top <N>` | How many results to show per level (default 20) |
| `-R`, `--recursive` / `--shallow` | Size folders du-style (default) vs. by their own files only |
| `--browse` / `--static` | Interactive folder browser (default in a terminal) vs. printed tree |
| `--tree` / `--flat` | Show recursive results as a tree (default) or a flat leaderboard |
| `--tree-depth <N>` | How many folder levels to expand in the tree (default 3) |
| `--depth <N>` | Max scan depth to walk (0 = unlimited) |
| `-f`, `--files` / `--dirs` | Scan individual files instead of directories |
| `-r`, `--root` / `--here` | Scan from `/` (re-runs with sudo) instead of the cwd |
| `-d`, `--hide-dotfiles` | Skip dotfiles / dotfolders |
| `-e`, `--exclude <pat>` | Add an exclude pattern (repeatable) |
| `--no-excludes` | Ignore the built-in junk excludes |
| `-c`, `--clean` | Sweep temp files before scanning |
| `-i` / `--no-interactive` | Toggle the post-scan deletion prompt |
| `--setup` | (Re)run the interactive setup wizard |
| `-y`, `--yes` | Accept defaults, never prompt for setup |
| `--config <path>` | Use an alternate config file |
| `-V`, `--version` | Print version and exit |

### Browser keys

| Key | Action |
| --- | --- |
| `↑`/`↓` or `k`/`j` | Move |
| `space` / `enter` / `→` | Expand into the highlighted folder (again to collapse) |
| `←` | Collapse, or jump back to the parent |
| `d` / `Del` | Delete the highlighted folder (asks first; sizes update live) |
| `q` / `Esc` | Quit (prints a summary of anything you freed) |

With `--static` (or when output is piped) you get the printed numbered tree
instead, and the deletion prompt takes those numbers comma-separated — each
confirmed before it's deleted.

### Examples

```bash
diskface                       # recursive folder tree under the current directory
diskface --flat                # same sizes, flat top-N leaderboard instead of a tree
diskface --tree-depth 5 -m 500 # expand 5 levels deep, only folders >= 500 MB
diskface -f                    # largest individual files instead of folders
diskface --root                # whole system (elevates with sudo)
diskface -e '*.iso' -e backups # add extra excludes on top of the defaults
diskface --no-excludes         # show everything, junk included
```

### Scan depth vs. accuracy

`--depth` bounds how deep diskface *walks*; `--tree-depth` bounds how deep the
tree is *shown*. Folder totals are accurate for everything within the scan
depth, so if a tree has very deep content, `--depth 0` gives fully accurate
du-style totals at the cost of a slower walk.

---

## Excludes

Exclusions come from three places, combined at scan time:

1. **Built-in app junk** (`APP_EXCLUDES` in `diskface.py`) — matched by folder/file
   name anywhere in the tree. Disable with `--no-excludes`.
2. **`extra_excludes`** in your config — your own always-on additions.
3. **`-e/--exclude`** flags — one-off additions for a single run.

Matching rules: an entry **without a slash** matches a basename anywhere
(`node_modules`, `.cache`, glob-aware); an entry **with a slash** matches the full
path (`/var/lib/docker`, or `**/foo` for any `.../foo`). When scanning with
`--root`, pseudo-filesystems like `/proc`, `/sys`, and `/dev` are always skipped.

---

## Configuration

`~/.config/diskface/config.json` holds your saved defaults. Every value can be
overridden by the matching CLI flag. A broken config is backed up and recreated
automatically.

```json
{
    "min_size_mb": 100,
    "top": 20,
    "max_depth": 8,
    "tree_depth": 3,
    "recursive": true,
    "tree_view": true,
    "scan_files": false,
    "hide_dotfiles": false,
    "browse": true,
    "interactive": true,
    "use_excludes": true,
    "extra_excludes": []
}
```

You can also add an optional `"temp_paths": [...]` array to override what
`--clean` sweeps.

---

## License

MIT.
