xgrep - Advanced Language-Specific Grep Tool

A powerful collection of specialized grep tools that search within specific programming language files using comprehensive file detection by extension, shebang analysis, and MIME type inspection. Features a hybrid approach that combines ripgrep's exceptional search performance with robust file type detection.

✨ Key Features

🎯 Language-Specific Search: Targeted searching in specific programming languages
- bashgrep: Search only in Bash script files (.sh, .bash, shebangs)
- phpgrep: Search only in PHP files (.php, .phtml, shebangs)
- pygrep: Search only in Python files (.py, .pyw, shebangs)
- xgrep: Search across all supported languages simultaneously
🔍 Comprehensive File Detection: Advanced file type detection using:
- File extensions: Standard extension-based detection
- Shebang analysis: Detects files by interpreter directives (#!/usr/bin/env python3)
- MIME type inspection: Uses file command for additional validation
- Binary detection: Automatically excludes binary files
⚡ Hybrid Performance: Best of both worlds approach
- Phase 1: Comprehensive file discovery using advanced detection
- Phase 2: High-speed search using ripgrep on discovered files
- Fallback: Graceful degradation to find+grep when ripgrep unavailable
📁 Smart Exclusions: Automatically excludes common directories:
- Build artifacts: .venv, node_modules, build/
- Version control: .git/, .svn/
- Temporary files: tmp/, .tmp/, temp/
- Cache directories: .cache/, __pycache__/
🎨 Terminal Integration: Automatic color output and formatting
⚙️ Flexible Configuration: Environment variables and command-line customization

📦 Installation

Quick Install

git clone https://github.com/Open-Technology-Foundation/xgrep.git
cd xgrep

System-Wide Installation

# Create symlinks for all tools
sudo ln -sf "$(pwd)/xgrep" /usr/local/bin/xgrep
sudo ln -sf "$(pwd)/xgrep" /usr/local/bin/bashgrep
sudo ln -sf "$(pwd)/xgrep" /usr/local/bin/phpgrep
sudo ln -sf "$(pwd)/xgrep" /usr/local/bin/pygrep

Local Installation

# Add to your PATH or create local symlinks
mkdir -p ~/.local/bin
ln -sf "$(pwd)/xgrep" ~/.local/bin/xgrep
ln -sf "$(pwd)/xgrep" ~/.local/bin/bashgrep
ln -sf "$(pwd)/xgrep" ~/.local/bin/phpgrep
ln -sf "$(pwd)/xgrep" ~/.local/bin/pygrep

Note: When run as xgrep, the tool automatically attempts to create convenience symlinks in /usr/local/bin if you have write permissions.

⚡ Performance Optimization

For optimal performance, install ripgrep:

# Ubuntu/Debian
sudo apt install ripgrep

# Fedora/RHEL/CentOS
sudo dnf install ripgrep

# macOS
brew install ripgrep

# Arch Linux
sudo pacman -S ripgrep

See ripgrep installation guide for additional platforms.

🚀 Usage

Basic Syntax

xgrep [options] [ripgrep_options] pattern [directory]

File Detection Examples

xgrep finds files using multiple detection methods:

# Files found by extension (.py, .sh, .php)
./script.py
./deploy.sh  
./config.php

# Files found by shebang (no extension needed)
./build-script     # #!/bin/bash
./web-tool         # #!/usr/bin/env python3
./cli-app          # #!/usr/bin/php

# Files found by MIME type analysis
./configure        # detected as shell script
./setup            # detected as Python script

Language-Specific Examples

# Find function definitions in Bash scripts
bashgrep "^function " ~/scripts

# Search for class declarations in PHP files
phpgrep "class [A-Z]" ~/webproject

# Find import statements in Python code
pygrep "^import|^from.*import" ~/python-projects

# Search for TODO comments across all supported languages
xgrep "TODO:|FIXME:" ~/development

# Case-sensitive search for specific error handling
bashgrep "(?-i)ERROR" ~/scripts

# Search with file listing only
pygrep -l "import requests" ~/projects

Advanced Usage

# Limit search depth and exclude specific directories
xgrep -d 2 -X "venv,node_modules" "api_key" ~/projects

# Reset exclusions and search everything
bashgrep -X '' "#!/bin/bash" ~/

# Use ripgrep options directly
phpgrep --rg -C 3 -n "class.*Controller" ~/webapp

# Debug mode to see what's happening
xgrep -D "pattern" ~/code

⚙️ Configuration Options

Command-Line Options

Option	Description	Example
`-d, --maxdepth N`	Limit search depth	`-d 3`
`-X, --exclude-dir DIR[,...]`	Exclude directories	`-X "tmp,cache"`
`-D, --debug`	Show debug information	`-D`
`-V, --version`	Display version	`-V`
`--help`	Show help message	`--help`
`--`, `--rg`	Pass options to ripgrep	`--rg -C 2 -n`

Environment Variables

Variable	Description	Default
`XGREP_EXCLUDE_DIRS`	Override excluded directories	`.venv .git bak temp tmp .tmp .temp .Trash-0`

File Detection

The tools intelligently detect files through:

Extensions: .sh, .bash (Bash) • .php, .phtml (PHP) • .py, .pyw (Python)
Shebangs: #!/bin/bash, #!/usr/bin/php, #!/usr/bin/python3, etc.
Exclusions: Common build/dependency directories automatically skipped

🔧 Integration Examples

Git Hooks

# Pre-commit hook to find debugging statements
#!/bin/bash
if pygrep -q "pdb\.set_trace|breakpoint\(\)" .; then
    echo "❌ Debugging statements found in Python files"
    exit 1
fi

Build Scripts

# Check for TODOs before release
if xgrep -q "TODO:|FIXME:" src/; then
    echo "⚠️  Outstanding TODOs found"
    xgrep "TODO:|FIXME:" src/
fi

Development Workflow

# Find all error handling patterns
bashgrep "trap|set -e" scripts/
phpgrep "try\s*{|catch\s*\(" src/
pygrep "try:|except|raise" app/

🧪 Testing

Run the comprehensive test suite:

# Run all tests
make test

# Run specific test categories  
make test-unit
make test-integration

# Verbose test output
make test-verbose

See TESTING.md for detailed testing information.

🤝 Contributing

We welcome contributions! Please see our development guide for:

Development environment setup
Code conventions and style
Testing requirements
Pull request process

Quick Development Setup

# Clone and setup
git clone https://github.com/Open-Technology-Foundation/xgrep.git
cd xgrep

# Install development dependencies
make check-deps

# Run linting and tests
make lint test

📋 Requirements

Bash 4.0+ (for associative arrays and modern features)
ripgrep (recommended for performance) or grep + find
BATS (for running tests)

🐛 Known Issues & Limitations

Shebang Detection: Limited by ripgrep's built-in file type definitions
Symlink Handling: Follows symlinks; may cause duplicate results in some cases
Performance: Fallback mode significantly slower than ripgrep on large codebases

See our issue tracker for current bugs and feature requests.

📄 License

This project is licensed under the GNU General Public License v3.0. See LICENSE for details.

👤 Author

Gary Dean - Open Technology Foundation

🔗 Related Projects

ripgrep - The fast search engine that powers xgrep
ag (The Silver Searcher) - Similar tool with different focus
ack - Another grep alternative

💡 Pro Tip: Use xgrep -D pattern directory to see exactly how your search is being executed and what files are being examined.