⚡ zs

Supercharged File Search Tool

Lightning-fast file searching with fuzzy matching, written in Zig

Features • Installation • Usage • Examples • Contributing

---

✨ Features

🚀 Blazing Fast Efficient recursive traversal Optimized scoring algorithm Minimal memory footprint	🎯 Smart Matching Fuzzy search algorithm Proximity-based scoring Substring matching
🎨 Beautiful Output Color-coded file types Clean, readable format Customizable display	⚙️ Highly Configurable Custom search paths Adjustable depth limits Flexible result filtering

🚀 Installation

Prerequisites

• Zig 0.14.0 or later

Building from Source

# Clone the repository
git clone https://github.com/Paol0B/zs.git
cd zs

# Build the release version
zig build -Doptimize=ReleaseFast

# The binary will be in zig-out/bin/zs

System-wide Installation

# Linux/macOS
sudo cp zig-out/bin/zs /usr/local/bin/

# Or add to your PATH
export PATH="$PATH:$(pwd)/zig-out/bin"

📖 Usage

📖 Usage

Basic Syntax

zs [options] <pattern>

Command Line Options

Option	Description	Default
-h, --help	Show help message	-
-p, --path <path>	Starting directory	/
-d, --depth <n>	Maximum search depth	10
-c, --case	Enable case-sensitive search	off
-l, --limit <n>	Maximum results to display	100
-n, --no-color	Disable colored output	off

💡 Examples

Basic Searches

# Find all files matching "main.zig"
zs main.zig

# Search in a specific directory
zs -p /home/user/projects config

# Limit search depth
zs -d 3 readme

Advanced Usage

# Case-sensitive search for exact matches
zs -c MyImportantFile

# Show more results
zs -l 500 test

# Search without colors (for piping)
zs -n package | grep -i json

# Combine multiple options
zs -p /usr/local -d 5 -l 20 -c binary

🎨 Color Coding

The output uses colors to help you quickly identify file types:

Color	File Type	Example
🔵 Blue	Directories	src/, config/
🟢 Green	Executables	zs, run.sh
🔴 Red	Archives	.zip, .tar.gz
🟣 Magenta	Images	.png, .jpg
🔷 Cyan	Audio	.mp3, .wav
⚪ White	Regular files	.txt, .md

🧠 How It Works

Fuzzy Matching Algorithm

The search engine uses a sophisticated scoring system:

Base Score Calculation:
├─ Character match: +10 points
├─ Consecutive matches: +5, +10, +15... (progressive)
├─ Start of string bonus: +20 points
├─ After separator bonus: +15 points (/, _, -, .)
└─ Length penalty: -1 per extra character

Search Strategy

1. Recursive Traversal: Efficiently walks directory trees
2. Dual Matching: Both fuzzy and substring matching
3. Smart Scoring: Ranks results by relevance
4. Thread-Safe: Concurrent directory scanning with mutex protection

Example Scoring

Pattern: "conf"

Results:
1. config.toml       (score: 95) ← exact prefix match
2. app.conf          (score: 85) ← contains exact pattern  
3. configuration.yml (score: 65) ← all chars match, longer name
4. src/config/       (score: 60) ← directory match

⚡ Performance Tips

🎯 Scope Your Search # Instead of searching everything zs pattern # Search specific directories zs -p ~/projects pattern zs -p /usr/local pattern	📊 Limit Depth # Deep searches take longer zs -d 20 pattern # Shallow searches are faster zs -d 3 pattern
🔢 Control Results # Fewer results = faster display zs -l 20 pattern # More results = more processing zs -l 1000 pattern	🚫 Skip System Dirs # Avoid /proc, /sys, /dev zs -p /home pattern zs -p /opt pattern

🛠️ Building for Development

# Debug build (faster compilation)
zig build

# Run directly
zig build run -- -p . test

# Run tests
zig build test

# Release with debug info
zig build -Doptimize=ReleaseSafe

# Smallest binary
zig build -Doptimize=ReleaseSmall

📊 Benchmarks

Performance on a standard system (SSD, 16GB RAM):

Directory	Files	Time	Results
/home/user	~50K	0.8s	145 matches
/usr/local	~20K	0.3s	67 matches
Small project	~1K	0.05s	12 matches

Note: Times may vary based on system specifications and disk I/O.

🙏 Acknowledgments

• Built with Zig - A general-purpose programming language
• Inspired by tools like fd, fzf, and ripgrep
• Thanks to the open-source community

🔗 Links

• Zig Language
• Report Issues
• Request Features

---

If you find this tool useful, please consider giving it a ⭐!

Made with ❤️ and Zig

Back to Top ↑