Skip to content

README.md

Latest commit

 

History

History
83 lines (59 loc) · 4.33 KB

README.md

File metadata and controls

83 lines (59 loc) · 4.33 KB

dirplot

CI PyPI Python Downloads License 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.

dirplot output

Features

  • Squarified treemap layout; file area proportional to size; ~500 extensions mapped to GitHub Linguist colours.
  • 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.
  • Animate git history (dirplot git), Mercurial history (dirplot hg), watch live filesystems (dirplot watch), and replay event logs (dirplot replay) — output APNG, MP4, or MOV.
  • Scan SSH hosts, AWS S3, GitHub repos (public and private), Docker containers, and Kubernetes pods — 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

# Standalone tool (recommended)
uv tool install dirplot

# Into the current environment
pip install dirplot

Optional extras: pip install "dirplot[ssh]", "dirplot[s3]", "dirplot[libarchive]".

dirplot watch uses watchdog for filesystem monitoring — installed automatically as a dependency.

dirplot git requires git on PATH; dirplot hg requires hg (Mercurial) on PATH. MP4 output (dirplot git, dirplot watch, dirplot replay with --animate) requires ffmpeg on PATH. dirplot read-meta on .mp4 files also requires ffprobe (bundled with ffmpeg).

Quick start

dirplot map .                                                    # current directory
dirplot map . --inline                                           # display in terminal
dirplot map . --output treemap.png --no-show                     # save to file
dirplot map . --log --inline                                     # log scale, inline
dirplot map github://pallets/flask                               # GitHub repo
dirplot map docker://my-container:/app                           # Docker container
dirplot map project.zip                                          # archive file
tree src/ | dirplot map                                          # pipe tree output

dirplot git . -o history.mp4 --animate                           # full git history
dirplot git . -o history.mp4 --animate --last 30d                # last 30 days
dirplot git github://owner/repo -o h.mp4 --animate --last 7d    # GitHub, last week

dirplot hg /path/to/repo -o history.png --animate               # full hg history
dirplot hg /path/to/repo@tip -o history.png                     # static, tip only

dirplot watch . --output treemap.png                             # live watch
dirplot watch . --output treemap.mp4 --animate                   # record as MP4

dirplot demo                                                     # run examples, save to ./demo/

Documentation

Development

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

See CONTRIBUTING.md for full details.

License

MIT — see LICENSE.