🌳 maram

A blazing-fast, modern alternative to the Unix tree command written in Rust

maram (മരം) - Malayalam word for "tree" - is a high-performance filesystem tree visualizer with advanced features like inline file sizes, line counts, powerful filtering, and beautiful visualizations.

---

✨ Features

🚀 Performance

• Blazing Fast - Custom iterative walker with parallelism
• Smart Filtering - Early pruning for efficiency
• Memory Efficient - Iterative traversal, no stack limits
• Platform Optimized - Direct syscalls on Unix/Linux

🎨 Rich Display

• Beautiful Trees - ASCII/Unicode visualization
• Inline Metrics - File sizes and line counts
• Size Charts - Visual disk usage distribution
• Colored Output - Syntax highlighting for clarity

🔍 Advanced Filtering

• Regex Patterns - Include/exclude with regex
• Size Ranges - Filter by file size
• Time-based - Filter by modification time
• Gitignore - Respect .gitignore files

🛠️ Flexibility

• Multiple Formats - Tree, JSON, CSV, plain text
• Configurable - Via ~/.maram.toml
• Cross-Platform - Linux, macOS, Windows
• Sorting Options - By name, size, time, type

📦 Installation

cargo install maram

git clone https://github.com/mufeedvh/maram
cd maram
cargo install --path .

# Coming soon
brew install maram

🚀 Quick Start

# Display current directory
maram

# Show files with sizes and line counts
maram --show-size --show-lines

# Beautiful Unicode tree with colors
maram -u --show-size

# Filter and sort Rust files by size
maram --include='\.rs$' --sort=size --reverse

# Show disk usage distribution
maram --dist=ext --format=chart

📸 Screenshots

📁 Basic Tree View

📊 Size Distribution Chart

🎯 Powerful Filtering

🎨 Unicode Tree with Colors

📈 Project Overview with Limits

📖 Usage

Basic Commands

Command	Description
maram	Display current directory tree
maram /path/to/dir	Display specific directory
maram -u	Use Unicode characters for tree
maram --show-lines	Show line counts for text files
maram --show-size	Show file sizes inline

Filtering Options

Option	Example	Description
--include	--include='\.rs$'	Include files matching regex
--exclude	--exclude='node_modules'	Exclude paths matching regex
--only-dirs	--only-dirs	Show only directories
--min-size	--min-size=1MB	Show files larger than size
--newer-than	--newer-than=1d	Show files modified recently
--gitignore	--gitignore	Respect .gitignore files

Display Options

Option	Example	Description
--sort	--sort=size --reverse	Sort by size (descending)
--max-files	--max-files=10	Limit files per directory
-L, --depth	-L 3	Maximum depth to traverse
--output	--output=json	Output format (tree/json/csv/plain)

Size Distribution

# Show size distribution by file type
maram --dist=type --format=chart

# Show top 20 largest files by extension
maram --dist=ext --top=20 --format=table

# Show distribution grouped by size buckets
maram --dist=size --format=chart

maram --help

🧱 Use as a Library (crate)

maram v0.2.0 exposes an ergonomic library API suitable for embedding in Rust projects. The library returns output to your code (as String or into any Write) instead of printing to stdout.

Quick start

use maram::{generate, MaramOptions, OutputFormat};

fn main() -> maram::Result<()> {
    let mut opts = MaramOptions::default();
    opts.output = OutputFormat::Tree;
    let rendered = generate(".", &opts)?;
    print!("{}", rendered);
    Ok(())
}

Streaming to a writer

use std::fs::File;
use maram::{generate_to_writer, MaramOptions, OutputFormat};

let mut opts = MaramOptions::default();
opts.output = OutputFormat::Plain;
let mut file = File::create("tree.txt")?;
generate_to_writer(".", &opts, &mut file)?;

Structured traversal + rendering

use maram::{collect, render, MaramOptions, OutputFormat};

let opts = MaramOptions::default();
let entries = collect(".", &opts)?;    // build structured tree

let mut json_opts = opts.clone();
json_opts.output = OutputFormat::Json;  // choose format at render time
let json = render(&entries, &json_opts)?;

Configuration via MaramOptions

• output: OutputFormat::{Tree, Json, Csv, Plain}
• filter: FilterOptions (regex include/exclude, depth, per-dir limits, sort, .gitignore, hidden files)
• format: FormatOptions (unicode, color, full path, show size/lines/dir sizes)
• threads: parallelism (0 = auto)
• max_file_size: limit for line counting
• total_size: add a total summary (Tree output)
• dir_sizes: compute recursive dir sizes
• distribution: optional (DistributionType, top: usize, DistributionFormat)

Convenience helpers:

let opts = MaramOptions::default()
    .with_line_counting(10 * 1024 * 1024) // 10MB
    .with_dir_sizes()
    .with_total_size();

Programmatic CLI behavior

If you still want to reuse the CLI’s Args + Config merging, but capture the output instead of printing to stdout:

use maram::{run_tree_output, Args, Config};
use std::path::Path;

let args = Args::default();
let config = Config::default();
let out = run_tree_output(Path::new("."), &args, &config)?;

Examples

Comprehensive examples live under examples/:

• examples/basic.rs – quick start tree rendering to String
• examples/json.rs – JSON output
• examples/filters.rs – filtering and depth limits
• examples/writer.rs – writing to a file
• examples/all.rs – full showcase of filters, formatting, distributions, and all APIs

Run any example:

cargo run --example all

⚡ Performance

maram is designed for speed and efficiency:

Benchmark	maram	tree	find	fd
Small directory (318 files)	2.2ms	4.1ms	3.0ms	29.6ms
Large directory (7,234 files)	12.4ms	89.5ms	29.8ms	198.3ms

Why is maram so fast?

• 🔧 Custom Walker - Optimized filesystem traversal with inline filtering
• 🚀 Zero Allocations - Pre-allocated buffers in hot paths
• ⚡ Direct Syscalls - Bypasses standard library overhead on Unix
• 🔀 Parallelism - Multi-threaded processing with rayon
• 🎯 Smart Pruning - Skip branches that don't match filters early

⚙️ Configuration

Create ~/.maram.toml to customize defaults:

[display]
unicode = true          # Use Unicode tree characters
show_size = true        # Always show file sizes
show_lines = false      # Show line counts
dir_sizes = false       # Calculate directory sizes
total_size = true       # Show total size summary

[filters]
show_hidden = false     # Show hidden files
gitignore = true        # Respect .gitignore
max_depth = 10          # Maximum traversal depth
max_files = 100         # Max files per directory
sort_by = "name"        # Sort by: name, size, time, type

[performance]
threads = 0             # CPU threads (0 = auto-detect)
max_file_size = 1073741824  # Max file size for line counting (1GB)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---