bestls

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
• 🎭 Customizable themes - Color by file type and extension via ~/.config/bestls/config.toml
• 📊 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

Theme Customization

Customize colors for your terminal:

# Initialize a theme config file
bestls theme init --show

# This creates ~/.config/bestls/config.toml with color options
# Edit to customize colors for file types and extensions

# Find your config file location
bestls theme path

# Reset to default colors
bestls theme reset

See THEMING.md for detailed configuration options and examples.

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

• EXAMPLES.md - Comprehensive usage examples and workflows
• THEMING.md - Color themes and customization guide
• CHANGELOG.md - Version history and release notes
• CONTRIBUTING.md - Guidelines for contributors
• ROADMAP.md - Planned features and development roadmap
• VERSION_POLICY.md - Version management and release process
• IMPLEMENTATION_SUMMARY.md - Technical implementation details

🛠️ Command Line Options

Core Options

Filtering Options

Output Options

Subcommands

🏗️ 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:

• 💡 Ideas & Feature Requests - Share your ideas for new features
• ❓ Q&A - Get help and ask questions
• 🛠️ Show and Tell - Share how you're using bestls
• 📢 Announcements - Stay updated with the latest news

🤝 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

• Email: mkm9284@gmail.com
• GitHub: @MurtadaNazar

🔗 Links

• Repository
• Issues
• Releases