file_tree_visualizer

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