Li - Enhanced Directory Listing Tool

A modern, feature-rich replacement for ls with colors, icons, and advanced display modes

Overview

Li is a powerful command-line utility that provides an enhanced replacement for the traditional ls command. Built with modern C++20 and std::filesystem, it offers beautiful colorized output, file type icons, multiple display modes, and extensive customization options without any external dependencies.

Features

Display Modes

Mode	Flag	Description
Grid	Default	Multi-column grid layout
Long	-l	Detailed listing with permissions, owner, size, and date
Table	-n	Clean table format with name and size
Two-Column	-N	Compact two-column format
Tree	-k	Hierarchical tree structure
Zebra	-z	Alternating row colors for better readability

Sorting Options

• By Name: -s name (default)
• By Size: -s size or -S
• By Time: -s time or -t
• By Extension: -s extension or -X
• By Type: -s type
• Reverse: -r or --reverse
• Directories First: -d or --dirs-first

Visual Enhancements

• Color Support: ANSI color codes for different file types
• File Type Icons: Nerd Font compatible icons for quick identification
• Zebra Striping: Alternating row backgrounds in long format
• Git Integration: Shows branch name and status indicators
• Human Readable Sizes: Automatic unit conversion (K, M, G, T)

File Type Recognition

• Directories: Blue bold with 📁 icon
• Executables: Green bold with ⚙️ icon
• Symlinks: Cyan with 🔗 icon
• Sockets: Magenta with ⚡ icon
• Pipes: Yellow with 📘 icon
• Archives: Red with 📦 icon
• Images: Magenta with 🖼️ icon
• Code Files: Language-specific colors and icons
• Hidden Files: Dim gray

Installation

From Source

# Clone the repository
git clone https://github.com/Lotus-OS-Core/list-viewer.git
cd list-viewer

# Build the project
make

# Install system-wide (requires root)
sudo make install

# Or install to ~/.local
make install DESTDIR=~/.local

Manual Installation

# Compile
g++ -std=c++20 -O2 -Wall -Wextra -o li src/*.cpp

# Install binary
sudo cp li /usr/local/bin/
sudo chmod 755 /usr/local/bin/li

# Install man page
sudo cp doc/li.1 /usr/local/share/man/man1/
sudo mandb -q

# Install shell completions
sudo cp doc/completion/li.bash /usr/share/bash-completion/completions/
sudo cp doc/completion/li.zsh /usr/share/zsh/site-functions/_li

Usage

Basic Usage

# List current directory
li

# List specific directory
li /usr/bin

# List with long format
li -l

# List with human readable sizes
li -lh

# List all files including hidden
li -a

Advanced Usage

# Recursive listing
li -R

# Tree view
li -k /usr

# Zebra striped listing
li -z

# Sort by size
li -lS

# Sort by modification time
li -lt

# Show git status
li --git

# Combine multiple options
li -lah --git

Display Modes

# Long format
li -l

# Table format
li -n

# Two-column format
li -N

# Tree view with sizes
li -K

# Zebra mode
li -z

Visual Customization

# Disable icons
li --no-icons

# Force colors
li --color=always

# Disable colors
li --color=never

# Custom directory color
li --color-dirs=cyan

Configuration

Configuration File

Create ~/.config/li/config.ini:

[general]
theme=dark
show_hidden=false
long_format=false
recursive=false
human_readable=true
dirs_first=true
show_icons=true
show_colors=true
sort_by=name
reverse_sort=false
time_style=long-iso
enable_git=true

[colors]
dir_color=blue
file_color=white
exec_color=green
link_color=cyan
special_color=yellow

Environment Variables

• COLUMNS: Override terminal column width
• TERM: Terminal type for color detection
• HOME: User's home directory for config lookup

Command Reference

Global Options

Short	Long	Description
(none)	--help	Show help message
-h, -H	--human-readable	Human readable sizes
-v	--version	Show version information
-c	--config	Use custom config file

Display Options

Short	Long	Description
-l	--long	Long listing format
-1	(none)	One file per line
-C	(none)	List in columns (default)
-x	(none)	List by lines
-n	--table	Table format
-N	--two-column	Two-column format
-k	--tree	Tree view
-K	(none)	Tree with sizes
-z	(none)	Zebra mode
-Z	(none)	Zebra with metadata

Filtering Options

Short	Long	Description
-a	--all	Show hidden files
-A	--almost-all	Show hidden except . and ..
-d	--dirs-first	Directories first
-f	(none)	No sort, enable -a

Sorting Options

Short	Long	Description
-r	--reverse	Reverse sort order
-t	(none)	Sort by time
-S	(none)	Sort by size
-X	(none)	Sort by extension
-s	--sort=TYPE	Sort by type

Information Options

Short	Long	Description
-i	--inode	Show inode numbers
-H	--human-readable	Human readable sizes
(none)	--si	SI units (1000 not 1024)
(none)	--stats	Show statistics
(none)	--git	Show git status

Visual Options

Short	Long	Description
-F	--classify	Add type indicators
(none)	--no-icons	Disable icons
(none)	--icons=WHEN	Icon mode (always/auto/never)
(none)	--color=WHEN	Color mode (always/auto/never)
(none)	--time-style=STYLE	Time format

Comparison with ls

Feature	ls	li
Basic listing	✓	✓
Long format	✓	✓
Hidden files	✓	✓
Recursive	✓	✓
Tree view	✗	✓
Zebra striping	✗	✓
File icons	✗	✓
Git status	✗	✓
Colors	✓	✓ (enhanced)
Configuration file	✗	✓
Shell completion	✗	✓

Platform Support

Platform	Status	Notes
Linux	✅ Full Support	Primary target
macOS	✅ Full Support	Minor differences
BSD	✅ Supported	POSIX compatibility
Windows	⚠️ WSL Only	Native not supported

Dependencies

• C++20 compatible compiler (g++ or clang++)
• Standard C++ library
• POSIX system calls

No external dependencies required!

Development

Building

# Debug build
make debug

# Release build (optimized)
make release

# Clean build artifacts
make clean

Testing

# Run tests
make test

Adding Features

The codebase is organized into modular components:

src/
├── main.cpp        # Entry point and orchestration
├── Args.hpp        # Command-line argument parsing
├── FileSystem.hpp  # Filesystem operations
├── Display.hpp     # Rendering engine
├── Theme.hpp       # Colors and icons
├── Utils.hpp       # Utility functions
├── Git.hpp         # Git integration
└── Config.hpp      # Configuration parsing

Troubleshooting

Colors not working

# Check terminal support
echo $TERM

# Force colors
li --color=always

Icons not displaying

• Install a Nerd Font: https://www.nerdfonts.com/
• Or disable icons: li --no-icons

Man page not accessible

# Update man database
mandb -q

# View man page
man li

Performance issues

For large directories, use:

li -1           # Single column
li --no-icons   # Disable icons
li --no-colors  # Disable colors

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

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

Author

LotusOS Core

Acknowledgments

• Inspired by the ms_replace_ls project - "Same Creator"
• Nerd Fonts for icon support
• The Linux community for inspiration

---

LotusOS Core - 2025,2026