Skip to content

README.md

Latest commit

 

History

History
113 lines (83 loc) · 6.54 KB

README.md

File metadata and controls

113 lines (83 loc) · 6.54 KB

dirplot

CI PyPI Python Downloads License Docs Buy Me a Coffee

dirplot creates nested treemap images for directory trees. It can display them in the system image viewer or inline in the terminal (iTerm2 and Kitty protocols, auto-detected). It also animates git history, watches live filesystems, and scans remote sources.

pip install dirplot
dirplot map .          # treemap of current directory, opens in system viewer
dirplot map . --inline # display inline in terminal (iTerm2 / Kitty / Ghostty)

dirplot output

Use cases

  • Find what's eating your disk — map ~/Downloads, ~/.cache, or node_modules across a monorepo to spot the culprits at a glance.
  • Inspect before you install — visualise a Python wheel, JAR, or RPM without unpacking it.
  • Understand a codebase instantly — map a legacy project or a large GitHub repo to grasp its structure before reading a single line.
  • Compare releases — diff two archive versions or two git tags to see exactly what grew, shrank, or disappeared.
  • Scan remote filesystems — map an SSH host, S3 bucket, Docker container, or Kubernetes pod without copying anything locally.
  • AI & data exploration — map a vector database, model weights directory, or agent memory folder (~/.claude/projects/).
  • Sysadmin at a glance — map /var/log to see which services generate the most logs, or scan a container image's filesystem layers.
  • Animate history — watch a repository or live filesystem evolve over time as a timelapse.

Features

  • Squarified treemap layout; file area proportional to size; per-extension colours (GitHub Linguist palette for known types, configurable Matplotlib colormap for the rest).
  • PNG, animated PNG (APNG), MP4, and MOV output for single frames and animations; interactive SVG for static maps; renders at terminal pixel size or a custom WIDTHxHEIGHT.
  • Inline terminal display — renders directly into iTerm2, Kitty, Ghostty, WezTerm, and Warp without opening a separate window; protocol auto-detected.
  • Animate git history (dirplot git), Mercurial history (dirplot hg), and replay filesystem event logs (dirplot replay) — output APNG, MP4, or MOV. Watch live filesystems (dirplot watch) with optional snapshot and event logging.
  • Scan metrics (dirplot metrics) — file/dir counts, total size, depth, top extensions by count or size, largest files and directories with percentage of total; JSON output supported.
  • Compare two trees (dirplot diff) — treemap diff of any two sources (local dirs, GitHub repos, archives, S3, SSH, Docker, K8s, or two commits/tags); dirplot diff . shows uncommitted changes; files sized by B; colour-coded borders show added (green), removed (red), and changed (blue) files. Git/hg repos scan only tracked files; change detection uses blob hashes (LFS-aware).
  • Scan SSH hosts, AWS S3, GitHub repos (public and private), Docker containers, Kubernetes pods, and Google Drive — no extra deps beyond the respective CLI.
  • Read archives directly (zip, tar, 7z, rar, jar, whl, …) without unpacking.
  • Works on macOS, Linux, and Windows (WSL2 fully supported).

Installation

# Try without installing (always fetches the latest release)
uvx dirplot@latest --version

# Recommended: isolated tool install via uv (fastest)
uv tool install dirplot

# Alternative: pipx (install pipx first if needed: brew install pipx on macOS)
pipx install dirplot

# Into the current environment
pip install dirplot

Optional extras — install only what you need:

Extra Enables Install
ssh Scan remote servers via SSH (adds paramiko) pip install "dirplot[ssh]"
s3 Scan AWS S3 buckets (adds boto3) pip install "dirplot[s3]"
libarchive Additional archive formats: .tar.zst, .iso, .dmg, .rpm, .cab, … (requires system libarchive) pip install "dirplot[libarchive]"

Other runtime requirements:

  • dirplot watch — watchdog is installed automatically.
  • dirplot git — requires git on PATH.
  • dirplot hg — requires hg (Mercurial) on PATH.
  • MP4 output (dirplot git, dirplot hg, dirplot replay) — requires ffmpeg on PATH.
  • dirplot meta on .mp4 files — requires ffprobe (bundled with ffmpeg).

Quick start

dirplot map .                                # current directory, opens in viewer
dirplot map . --inline                       # display in terminal (iTerm2/Kitty/Ghostty)
dirplot map . --output treemap.png --no-show # save to file
dirplot map . --log-scale 4                  # log scale when one file dominates
dirplot map github://pallets/flask           # GitHub repo
dirplot map project.zip                      # archive — no unpacking needed

dirplot diff .                               # uncommitted changes
dirplot diff .@HEAD~5 .@HEAD                 # last 5 commits

dirplot metrics .                            # file counts, sizes, top extensions
dirplot git . --range main --output h.mp4    # full git history as MP4

See the full documentation for the complete command reference.

Documentation

Full documentation is available at deeplook.github.io/dirplot.

Development

git clone https://github.com/deeplook/dirplot
cd dirplot
make test

See CONTRIBUTING.md for full details.

A significant portion of this codebase was developed with AI assistance (primarily Claude by Anthropic). All generated code was reviewed and curated by the author.

License

MIT — see LICENSE.