ff - Fast File Finder

A blazingly fast file finder with live preview, syntax highlighting, and fuzzy search. Built in modern C++17.

Features

• 🚀 Fast - Multi-threaded directory scanning, 2-5x faster than find
• 🔍 Multiple search modes - Glob patterns, regex, and fuzzy matching
• 👁️ Live preview - Syntax-highlighted file preview in split view
• ⌨️ Vim-style navigation - j/k, g/G, Ctrl+d/u
• 🎨 Syntax highlighting - C/C++, Python, JavaScript, TypeScript, Rust, Go, and more
• 📋 Clipboard integration - Copy file paths with a single keystroke
• 🎯 Smart filtering - Filter by extensions, ignore common directories

Installation

Quick Install (recommended)

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/0xXrer/ff/refs/heads/master/install.sh | bash

Windows (PowerShell as Administrator):

irm https://raw.githubusercontent.com/0xXrer/ff/refs/heads/master/install.ps1 | iex

Download Binary

Download the latest release for your platform from Releases:

Platform	Architecture	Download
Linux	x86_64	ff-linux-x86_64.tar.gz
macOS	Intel	ff-macos-x86_64.tar.gz
macOS	Apple Silicon	ff-macos-arm64.tar.gz
Windows	x86_64	ff-windows-x86_64.zip

Build from Source

Prerequisites: CMake 3.15+, C++17 compiler (GCC 8+, Clang 7+, MSVC 2019+)

git clone https://github.com/0xXrer/ff.git
cd ff
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --config Release

# Install (Linux/macOS)
sudo cmake --install .

# Or copy manually
sudo cp ff /usr/local/bin/   # Linux/macOS
copy Release\ff.exe C:\Windows\  # Windows (Admin)

Usage

Basic usage

# Find all C++ files
ff "*.cpp"

# Regex search
ff --regex "test_.*\.h$"

# Fuzzy search
ff "main" --fuzzy

# Search in specific directory
ff "*.rs" --path ./src

# Filter by extensions
ff --ext cpp,hpp,h

# No preview (batch mode, prints paths)
ff "*.py" --no-preview

Options

Option	Description
-h, --help	Show help message
-v, --version	Show version
-r, --regex	Use regex pattern matching
-f, --fuzzy	Use fuzzy matching (like fzf)
-p, --path <DIR>	Search in specific directory
-e, --ext <EXT,...>	Filter by extensions
-d, --depth <N>	Maximum recursion depth (default: 10)
-i, --case-sensitive	Case-sensitive matching
-H, --hidden	Include hidden files
-n, --no-preview	Disable preview panel

Keyboard shortcuts

Key	Action
j / ↓	Move down
k / ↑	Move up
J / K	Scroll preview down/up
d / u	Page down/up
g / G	Go to top/bottom
p	Toggle preview panel
y	Copy path to clipboard
Enter	Select file, copy path, exit
q / Esc	Quit

Examples

Find source files

ff "*.cpp" --ext cpp,hpp,h,c

Search for test files

ff --regex "^test_.*\.py$" --path ./tests

Fuzzy find

ff "mncpp" --fuzzy  # Matches "main.cpp", "manager.cpp", etc.

Quick file lookup

ff "config" --fuzzy --path ~/projects

Architecture

src/
├── main.cpp        # CLI entry point
├── scanner.cpp     # Multi-threaded directory traversal
├── matcher.cpp     # Glob/regex/fuzzy matching
├── previewer.cpp   # File content loading
├── highlighter.cpp # Syntax highlighting
├── tui.cpp         # Terminal UI (FTXUI)
└── clipboard.cpp   # Cross-platform clipboard

Performance

Compared to traditional find on a directory with 100,000 files:

Tool	Time
find	2.1s
fd	0.8s
ff	0.7s

Benchmarked on NVMe SSD, Linux 6.1, AMD Ryzen 7

Dependencies

• FTXUI - Terminal UI library
• fmtlib - Modern formatting library

Both are fetched automatically by CMake.

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! Please read the contributing guidelines first.

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

Roadmap

• Configuration file support (~/.config/ff/config.toml)
• Custom color schemes
• File type icons (Nerd Fonts)
• Integration with editors (open in $EDITOR)
• Bookmark frequently accessed files
• Search inside file contents (grep mode)