Project

file_tree_visualizer

0.0
The project is in a healthy, maintained state
file_tree_visualizerjohnbidwellb/file-tree-visualizerHomepageDocumentationSource CodeBug TrackerWiki
Scans a directory recursively, computes file/directory sizes, and generates an HTML report rendered with React.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
509
Stars
0
Forks
0
Watchers
0
 Releases
Current version
0.2.1
Total releases
4
First release
2026-04-04
Latest release
2026-04-04
 Pull Requests
Open Pull Requests
2
Closed Pull Requests
0
Merged Pull Requests
0
Pull Request Acceptance Rate
0%
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2026-04-04
Reverse Dependencies
0

 Dependencies

Runtime

csv
~> 3.3
 Project Readme

file_tree_visualizer

CI RubyGems

Ruby gem to scan file trees from the terminal and generate a fully offline interactive HTML report with the items that consume the most disk space.

What it does

  • Recursively scans a directory.
  • Computes cumulative size per directory and size per file.
  • Generates an HTML report with:
    • Expand/collapse file tree.
    • Text and minimum-size filters.
    • Ranking of the largest files.
    • No external dependencies (works offline).

Quick usage (without installing the gem)

ruby bin/file-tree-visualizer /path/to/scan -o report.html

Install from RubyGems

Gem page: https://rubygems.org/gems/file_tree_visualizer

gem install file_tree_visualizer
file-tree-visualizer /path/to/scan -o report.html

Install a specific version:

gem install file_tree_visualizer -v 0.2.1

Local development install

bundle install
gem build file_tree_visualizer.gemspec
gem install ./file_tree_visualizer-0.2.1.gem
file-tree-visualizer /path/to/scan -o report.html

Options

file-tree-visualizer [path] [options]

If no `path` is provided, the current directory is scanned by default.

During scanning, an interactive terminal shows a progress bar with processed files/directories vs discovered totals.

    -o, --output FILE           Output HTML file (default: file-tree-report.html)
    -t, --top N                 Number of largest files to keep in ranking (default: 200)
        --follow-symlinks       Follow symbolic links
        --no-progress           Disable progress bar
        --exclude PATTERNS      Exclude patterns (comma-separated or repeated)
        --summary               Print summary to terminal
        --json FILE             Export full result as JSON
        --csv FILE              Export top files as CSV
        --lang LANG             Language for CLI and report (en|es)
    -v, --version               Print version
    -h, --help                  Show help

Language resolution priority:
- `--lang`
- `LANG` environment variable (for example `es_CL.UTF-8`)
- fallback to English (`en`)

Common workflows

Print current gem version:

file-tree-visualizer --version

Summary only (no HTML file generated unless --output is explicitly provided):

file-tree-visualizer --summary

Summary + HTML report:

file-tree-visualizer . --summary --output report.html

Exclude directories and files by pattern:

file-tree-visualizer . --exclude "node_modules,.git,*.log" --exclude "tmp/**"

Export JSON and CSV in one run:

file-tree-visualizer . --summary --json scan.json --csv top-files.csv

Contributing

  1. Create a feature branch from main.
  2. Implement your change and run tests locally.
  3. Push your branch and open a Pull Request.
  4. Wait for CI to pass and at least one approval.
git checkout -b feat/short-description
bundle exec rake test
git push origin feat/short-description

Branch policy:

  • For collaborators, main is protected and requires PR + CI + approval.
  • Repository admins can bypass these rules when needed.

Automatic release to RubyGems

  • This repository publishes the gem automatically when pushing a tag with format v* (for example v0.2.1).
  • Before using it, configure the RUBYGEMS_API_KEY secret in GitHub Actions.
  • You can also trigger the workflow manually from GitHub Actions (workflow_dispatch).
git tag v0.2.1
git push origin v0.2.1

Reusable release notes template:

gh release create v0.2.1 --title "v0.2.1" --notes-file .github/release-template.md