How emad-elsaid/dirtree works
1. What this repo is
- dirtree is a single Ruby gem/CLI tool that turns a list of file paths into an HTML visualization of a directory tree.
- It is not a server or web app; the primary runtime is the Ruby CLI, and the final artifact is static HTML viewed in a browser.
2. Top-level execution path
- The user runs exe/dirtree with file paths from arguments or stdin.
- The CLI selects a template, builds an in-memory tree from the input paths, renders HTML, and either prints it to stdout or writes it to a file via -o.
3. Core domain model
- lib/dirtree/node.rb is the main data model boundary.
- It likely represents hierarchical nodes for directories/files and the relationships needed to aggregate a flat path list into a tree structure.
4. Library entry point
- lib/dirtree.rb is the gem’s main require point and orchestrator for the library side.
- This is where the CLI-facing functionality is exposed to the executable and where the app’s internal pieces are wired together.
5. Template rendering layer
- templates/ contains four ERB HTML templates: tree, circles, flame, and treemap.
- The templates are the presentation boundary: they transform the same tree data into different visual encodings without changing the underlying model.
6. Data flow from input to visualization
- Input is a stream of file paths, typically from git ls-files, find, ag -l, or shell globbing.
- Those paths are normalized into a tree structure, then serialized into HTML/JS inside one of the ERB templates, producing a standalone page.
7. Output modes
- The default output is HTML to stdout, which supports shell piping and redirection.
- -o writes to a file, making the tool usable both in pipelines and as a report generator.
8. Asset/loading boundary
- The README’s --local-dependencies option indicates the generated HTML can either reference remote JavaScript libraries or use bundled/local ones.
- That means visual rendering is split between server-side Ruby template generation and browser-side JS/CSS assets.
9. Optional screenshot path
- The --screenshot option suggests an additional export mode that captures the generated visualization as an image.
- Architecturally, this is a secondary output pipeline layered on top of the same HTML generation path.
10. CLI ergonomics
- exe/dirtree-completion.bash provides shell completion, showing the project treats the CLI as the primary user interface.
- The executable and completion script are packaging concerns around the same core library.
11. Packaging and release boundary
- dirtree.gemspec, Gemfile, and Rakefile define the gem packaging, dependencies, and release/build workflow.
- lib/dirtree/version.rb isolates version metadata for the gem and CLI version flag.
12. What to show in an architecture diagram
- A good diagram would show: input sources → CLI/executable → path-to-tree model (Node) → template renderer (ERB templates) → HTML output → browser rendering.
- Optional branches should show local-vs-remote JS assets and the screenshot/export mode as separate terminal paths.
Main entry points: node.rb Node · dirtree dirtree · dirtree.gemspec Gem build · dirtree.rb Library API
Components 19
CLI
Executable entrypoints and user-facing command flow
- File paths · Paths read from arguments, stdin, or shell pipelines
- dirtree · Primary executable that parses options and drives rendering
exe/dirtree - Completion · Bash completion for the CLI
exe/dirtree-completion.bash - Stdout · Default output stream for piping and redirection
- Output file · File written with the -o option
Core
Library entrypoint and tree model
- Library API · Main require point wiring the library-side functionality
lib/dirtree.rb - Node · Hierarchical data model for directories and files
lib/dirtree/node.rb
Templates
Alternative HTML visual encodings
- Tree view · Indented tree visualization
templates/tree.html.erb - Circles view · Circle-based visualization
templates/circles.html.erb - Flame view · Flame-style visualization
templates/flame.html.erb - Treemap view · Treemap visualization
templates/treemap.html.erb - Local assets · Switches generated HTML between remote and bundled browser dependencies
- HTML page · Standalone visualization emitted by the templates
- Browser · Renders the generated static HTML page
- Screenshot · Optional image capture layered on top of HTML generation
Packaging
Gem and release metadata
- Version · Gem and CLI version metadata
lib/dirtree/version.rb - Gem build · Gem specification, dependencies, and release workflow
dirtree.gemspec - Dependencies · Bundler dependency definition
Gemfile - Rake tasks · Build and release automation
Rakefile
Connections 21
- File paths → dirtree: provide paths · CLI consumes paths from args or stdin
- dirtree → Library API: invoke library · Executable delegates orchestration to the library entry point
- Library API → Node: build tree · Library turns normalized paths into hierarchical nodes
- Node → Tree view: render data · Tree model feeds the selected ERB template
- Node → Circles view: render data · Same tree model supports alternate visual encodings
- Node → Flame view: render data · Same tree model supports alternate visual encodings
- Node → Treemap view: render data · Same tree model supports alternate visual encodings
- Tree view → HTML page: emit html · Template produces the standalone page
- Circles view → HTML page: emit html · Template produces the standalone page
- Flame view → HTML page: emit html · Template produces the standalone page
- Treemap view → HTML page: emit html · Template produces the standalone page
- Local assets → HTML page: load assets · Generated HTML can reference remote or bundled browser dependencies
- HTML page → Stdout: print · Default mode writes HTML to standard output
- HTML page → Output file: write -o · Optional file output path
- HTML page → Browser: view · Browser consumes the generated static page
- HTML page → Screenshot: capture · Optional export path for a rendered image
- Completion → dirtree: assist · Shell completion supports the primary CLI
- Gem build → dirtree: ship · Gem packaging installs the executable
- Dependencies → Gem build: deps · Bundler feeds dependency resolution
- Rake tasks → Gem build: automation · Rake handles build and release tasks
- Version → Gem build: versioning · Version metadata is consumed by packaging and CLI flags