bestls 1.3.0

A fast and colorful Rust-based ls replacement CLI tool with JSON output and sorting options.
bestls-1.3.0 is not a library.

bestls

Rust License: MIT GitHub Discussions Version: 1.3.0

A fast, colorful, and Rust-powered replacement for the traditional ls command.

bestls provides human-readable file listings in both pretty tables and JSON formats, with powerful filtering, tree view, and modern CLI conveniences built for speed and usability.

âœĻ Features

  • ðŸŽĻ Colorful output - Beautiful colored tables with optional color controls
  • 📊 Multiple formats - Tables, compact JSON, pretty JSON, or single-column compact mode
  • ⚡ Blazing fast - Parallel metadata fetching with Rayon
  • 📏 Human-readable - File sizes in KB, MB, GB format with conversions
  • 🔧 Flexible sorting - Sort by name, size, or modification date
  • ðŸŒģ Tree view - Recursive directory traversal with depth control
  • 🔍 Smart filtering - Filter by extension, pattern, and file size
  • 👁ïļ Hidden files - View hidden files with --all flag
  • 🔒 File permissions - Unix-style permission display (rwxrwxrwx)
  • ðŸ‘Ĩ Owner info - File owner and group information
  • ðŸ“Ī Export data - Save results to files, JSON formats for automation
  • 🔄 Shell completion - Tab-completion for Bash, Zsh, and Fish
  • ðŸŠķ Lightweight - Single binary with no runtime dependencies

ðŸ“Ķ Installation

From crates.io

cargo install bestls

From source

git clone https://github.com/MurtadaNazar/bestls.git
cd bestls
cargo build --release

The binary will be available at target/release/bestls.

🚀 Quick Start

Basic Usage

# List current directory
bestls

# List specific directory
bestls -p /path/to/directory

# Include hidden files
bestls -a

# Sort by size
bestls --sort size

Filtering & Tree View

# Show only Rust files
bestls --filter-ext rs

# Recursive tree view (limit depth to 2)
bestls --tree --depth 2

# Find files between 1KB and 10MB
bestls --min-size 1KB --max-size 10MB

# Pattern matching
bestls --filter-name "*.md"

Output Options

# Compact single-column output
bestls --compact

# Export as JSON
bestls --format json --out results.json

# Pretty JSON
bestls --format json-pretty

# No colors (for piping/scripts)
bestls --no-color

Advanced Examples

# Find large Rust files sorted by size
bestls -p src --filter-ext rs --min-size 5KB --sort size

# Export directory structure as JSON
bestls --tree --depth 3 --format json --out structure.json

# Filter markdown files and export
bestls --filter-ext md --json-pretty --out docs_list.json

Shell Completions

Enable tab-completion in your shell:

# For Bash
bestls completion bash > ~/.local/share/bash-completion/completions/bestls

# For Zsh (add to .zshrc: fpath=(~/.zfunc $fpath))
bestls completion zsh > ~/.zfunc/_bestls

# For Fish
bestls completion fish > ~/.config/fish/completions/bestls.fish

📖 Documentation

🛠ïļ Command Line Options

Core Options

Option Short Description
--path -p Directory path to list
--sort -s Sort by: name, size, date
--all -a Show hidden files (starting with .)
--help -h Show help information
--version -V Show version information

Filtering Options

Option Description
--tree Recursive directory listing
--depth N Maximum recursion depth
--filter-ext Filter by extensions (comma-separated)
--filter-name Filter by filename pattern (glob-style)
--min-size Minimum file size (e.g., 1KB, 1MB)
--max-size Maximum file size (e.g., 10MB, 1GB)

Output Options

Option Description
--format Output format: table, json, json-pretty
--compact Single-column output mode
--columns Select visible columns
--out Export output to file
--no-color Disable colored output
--json Compact JSON (legacy)
--json-pretty Pretty JSON (legacy)

Subcommands

Command Description
completion Generate shell completions

🏗ïļ Building from Source

Prerequisites

  • Rust 1.85.0 or later
  • Cargo package manager

Build Steps

  1. Clone the repository:

    git clone https://github.com/MurtadaNazar/bestls.git
cd bestls

  2. Build the project:

    cargo build --release

  3. (Optional) Install globally:

    cargo install --path .

💎 Community

Join our community discussions! We'd love to hear from you:

ðŸĪ Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

For more details, see CONTRIBUTING.md.

📄 License

This project is licensed under:

  • MIT License - See LICENSE for details

ðŸ‘Ļ‍ðŸ’ŧ Author

Murtaza Nazar

🔗 Links