luff

A production-grade CLI tool for printing file contents with multiple output formats, written in Rust.

Features

• Multiple Output Formats: Markdown code blocks, tree view
• Smart File Discovery: Directory walking with gitignore support
• Clipboard Integration: Copy output directly to system clipboard
• Security Hardened: Protection against path traversal, symlink attacks, resource exhaustion
• High Performance: Upfront collection with minimal allocations, efficient I/O
• Well Tested: Unit tests, property-based tests, integration tests, E2E tests
• Modular Architecture: Clean separation of concerns, easy to extend

Installation

From Source

git clone https://github.com/owlroute/luff.git
cd luff
cargo install --path .

Development Build

cargo build --release
./target/release/luff --help

Usage

Process Specific Files

Print specific files with Markdown formatting:

luff -f src/main.rs Cargo.toml

Walk Current Directory

Print all files in the current directory:

luff

Walk from Git Root

Start from the git repository root:

luff -g

Respect .gitignore (default)

Honor gitignore patterns when walking (on by default):

luff

Include Ignored Files

Include files that .gitignore would normally skip:

luff --ignored

Include Hidden Files

Include dot-directories and files:

luff -d

Tree Output Format

Display as a tree structure:

luff --format tree

Limit Directory Depth

Only traverse up to N levels deep:

luff --max-depth 3

Copy to Clipboard

Copy output to system clipboard (also prints to stdout):

luff -c

Clipboard Only (No Stdout)

Copy to clipboard without printing to terminal:

luff -c -S

Enable Debug Logging

Show detailed information about file processing:

luff -v

Combined Options

# Walk git repo, include ignored files, include dotfiles, debug output
luff -g -I -d -v

# Process specific files with tree format
luff -f src/*.rs --format tree

# Walk with depth limit and copy to clipboard
luff --max-depth 2 -c

# Clipboard-only mode with tree format
luff --format tree -c -S

Options

Output Modes

Note: Clipboard mode requires buffering the entire output in memory before writing. For large codebases, this may use significant memory.

Architecture

Key Design Decisions

• Upfront Collection: Directory walker collects file paths at construction to prevent output file inclusion
• Shell Redirection Protection: Skips empty files created within 2 seconds to avoid including luff > output.txt output
• Zero-cost Abstractions: Walker enum provides unified interface without runtime overhead
• Security First: All file operations validated against path traversal, size limits, symlink attacks
• Explicit Error Handling: No panics in library code, Result types throughout

Development

Prerequisites

• Rust 1.85 or later
• Git (for git-related functionality)
• Clipboard support (X11/Wayland on Linux, native on macOS/Windows)

Building

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run with arguments
cargo run -- --help

Testing

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_normalize_path

# Run integration tests only
cargo test --test integration_test

# Run E2E tests
cargo test --test e2e_test

# Run with property-based tests
cargo test --features proptest

Benchmarking

# Run all benchmarks
cargo bench

# Run specific benchmark
cargo bench walker_small

# Generate HTML reports
cargo bench -- --save-baseline my-baseline

Code Quality

# Check for issues
cargo clippy

# Format code
cargo fmt

# Check for unsafe code
cargo geiger

Security

This project follows security best practices:

• Path Validation: All paths validated against traversal attacks
• Size Limits: Files limited to 100MB to prevent memory exhaustion
• TOCTOU Protection: File metadata re-checked after open
• Symlink Safety: Canonicalization with validation
• Input Sanitization: All user input validated
• No Unsafe Code: Pure safe Rust (verify with cargo geiger)
• Root Containment: File list mode prevents access outside project root
• Timeout Protection: File operations have 5-second timeout to prevent FIFO blocking

Platform Support

• Linux: Full support (X11 or Wayland required for clipboard)
• macOS: Full support (native clipboard)
• Windows: Full support (native clipboard)
• Headless: Works without clipboard (graceful degradation)