Fast Finder

A fast and efficient command-line utility for finding files and directories by name pattern with configurable depth limits.

Features

• 🔍 Fast file and directory search using fd (with find fallback)
• 📁 Dual commands: fff for files, ffd for directories
• 🎯 Pattern matching with case-insensitive search
• 🏔️ Configurable depth limits (default: 5 levels)
• 🚀 Infinite depth option for complete directory traversal
• 🛡️ Input validation and error handling
• ⚙️ Customizable configuration via config.sh
• 🎨 Colored output and user-friendly messages

Installation

1. Run the installation script:

   ./install.sh

2. Ensure your ~/bin directory is in your PATH:

   export PATH="$PATH:$HOME/bin"

3. Verify installation:

   which fff ffd

Usage

Basic Usage

# Find files matching pattern (case-insensitive)
fff myname

# Find directories matching pattern  
ffd myname

# Search with custom depth
fff myname -5

# Search with infinite depth
fff myname -i

# Show active runtime settings (including excluded dirs)
fff myname --verbose

# Show help
fff --help

Examples

# Find all Python files in current directory (5 levels deep)
fff py

# Find all README files with unlimited depth
fff readme -i

# Find all 'src' directories (5 levels deep)
ffd src -5

# Find files with spaces in name
fff "my file"

# Find configuration files
fff cfg

Configuration

Edit config.sh to customize defaults:

# Maximum search depth (1-20)
DEFAULT_MAX_DEPTH=5

# Case sensitivity
CASE_SENSITIVE=false

Command Line Options

Option	Description
<pattern>	Search pattern (automatically wrapped with *pattern*)
-<depth>	Maximum search depth (e.g., -5 for depth 5)
-i	Infinite depth (no maxdepth limit)
-v, --verbose	Print active runtime settings
-h, --help	Show usage information

Search Patterns

• Patterns are automatically wrapped with * for flexible matching
• Search is case-insensitive by default
• Wildcards * and ? in search patterns are treated literally
• Spaces in patterns should be quoted: fff "my file"

Safety Features

• Input validation for patterns and depth values
• Reasonable depth limits (1-20) to prevent system overload
• Error control with set -euo pipefail
• Maximum 20 results for performance
• Default excluded directories: .git, .hg, .svn, .venv, venv

Environment Variables

• FAST_FINDER_EXCLUDE_DIRS: comma-separated directory names to exclude (default: .git,.hg,.svn,.venv,venv)
• FAST_FINDER_INCLUDE_HIDDEN: true|false (default: true)
• FAST_FINDER_FOLLOW_SYMLINKS: true|false (default: true)
• FAST_FINDER_COLOR: auto|always|never (default: auto)
  • auto means color is shown only when output is a terminal (TTY)
• FAST_FINDER_DEBUG: true|false (default: false)
  • prints backend, resolved settings, and the effective search command
• FAST_FINDER_MAX_RESULTS: positive integer result cap (default: 20)

Files

• fast-finder.sh - Main search engine
• bin/fff - File finder wrapper
• bin/ffd - Directory finder wrapper
• config.sh - Configuration settings
• install.sh - Installation script

License

This is a free and open-source utility.