{"id":29085190,"url":"https://github.com/open-technology-foundation/xgrep","last_synced_at":"2026-05-05T09:31:38.045Z","repository":{"id":279940309,"uuid":"940512262","full_name":"Open-Technology-Foundation/xgrep","owner":"Open-Technology-Foundation","description":"Specialized grep tools to search within specific language files by extension and shebang detection. Utilizes ripgrep for performance when available, with graceful fallback to standard grep.","archived":false,"fork":false,"pushed_at":"2026-01-21T23:46:30.000Z","size":92,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-22T11:53:39.314Z","etag":null,"topics":["bash","grep","grep-search","php","python"],"latest_commit_sha":null,"homepage":"https://yatti.id/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Open-Technology-Foundation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"AUDIT-EVALUATE.md","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-28T10:00:00.000Z","updated_at":"2026-01-21T23:46:48.000Z","dependencies_parsed_at":"2025-02-28T16:58:36.209Z","dependency_job_id":"a1165d7a-8b2c-447f-b259-d55ddf6fe0a2","html_url":"https://github.com/Open-Technology-Foundation/xgrep","commit_stats":null,"previous_names":["open-technology-foundation/xgrep"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Open-Technology-Foundation/xgrep","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fxgrep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fxgrep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fxgrep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fxgrep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Open-Technology-Foundation","download_url":"https://codeload.github.com/Open-Technology-Foundation/xgrep/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fxgrep/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32643520,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"online","status_checked_at":"2026-05-05T02:00:06.033Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","grep","grep-search","php","python"],"created_at":"2025-06-27T22:30:57.323Z","updated_at":"2026-05-05T09:31:38.034Z","avatar_url":"https://github.com/Open-Technology-Foundation.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xgrep - Advanced Language-Specific Grep Tool\n\n[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n\nA 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.\n\n## Key Features\n\n- **Language-Specific Search**: Targeted searching in specific programming languages\n  - `bashgrep`: Search only in Bash script files (`.sh`, `.bash`, shebangs)\n  - `phpgrep`: Search only in PHP files (`.php`, `.phtml`, shebangs)  \n  - `pygrep`: Search only in Python files (`.py`, `.pyw`, shebangs)\n  - `xgrep`: Search across all supported languages simultaneously\n\n- **Comprehensive File Detection**: Advanced file type detection using:\n  - **File extensions**: Standard extension-based detection\n  - **Shebang analysis**: Detects files by interpreter directives (`#!/usr/bin/env python3`)\n  - **MIME type inspection**: Uses `file` command for additional validation\n  - **Binary detection**: Automatically excludes binary files\n\n- **Hybrid Performance**: Best of both worlds approach\n  - **Phase 1**: Comprehensive file discovery using advanced detection\n  - **Phase 2**: High-speed search using ripgrep on discovered files\n  - **Fallback**: Graceful degradation to find+grep when ripgrep unavailable\n\n- **Smart Exclusions**: Automatically excludes common directories:\n  - Build artifacts: `.venv`, `node_modules`, `build/`\n  - Version control: `.git/`, `.svn/`\n  - Temporary files: `tmp/`, `.tmp/`, `temp/`\n  - Cache directories: `.cache/`, `__pycache__/`\n\n- **Terminal Integration**: Automatic color output and formatting\n- **Flexible Configuration**: Environment variables and command-line customization\n\n## Installation\n\n### Quick Install\n\n```bash\ngit clone https://github.com/Open-Technology-Foundation/xgrep.git\ncd xgrep\n```\n\n### System-Wide Installation\n\n```bash\n# Create symlinks for all tools\nsudo ln -sf \"$(pwd)/xgrep\" /usr/local/bin/xgrep\nsudo ln -sf \"$(pwd)/xgrep\" /usr/local/bin/bashgrep\nsudo ln -sf \"$(pwd)/xgrep\" /usr/local/bin/phpgrep\nsudo ln -sf \"$(pwd)/xgrep\" /usr/local/bin/pygrep\n```\n\n### Local Installation\n\n```bash\n# Add to your PATH or create local symlinks\nmkdir -p ~/.local/bin\nln -sf \"$(pwd)/xgrep\" ~/.local/bin/xgrep\nln -sf \"$(pwd)/xgrep\" ~/.local/bin/bashgrep\nln -sf \"$(pwd)/xgrep\" ~/.local/bin/phpgrep\nln -sf \"$(pwd)/xgrep\" ~/.local/bin/pygrep\n```\n\n**Note**: When run as `xgrep`, the tool automatically attempts to create convenience symlinks in `/usr/local/bin` if you have write permissions.\n\n## Performance Optimization\n\nFor optimal performance, install ripgrep:\n\n```bash\n# Ubuntu/Debian\nsudo apt install ripgrep\n\n# Fedora/RHEL/CentOS\nsudo dnf install ripgrep\n\n# macOS\nbrew install ripgrep\n\n# Arch Linux\nsudo pacman -S ripgrep\n```\n\nSee [ripgrep installation guide](https://github.com/BurntSushi/ripgrep#installation) for additional platforms.\n\n## Usage\n\n### Basic Syntax\n\n```bash\nxgrep [options] [ripgrep_options] pattern [directory]\n```\n\n### File Detection Examples\n\nxgrep finds files using multiple detection methods:\n\n```bash\n# Files found by extension (.py, .sh, .php)\n./script.py\n./deploy.sh  \n./config.php\n\n# Files found by shebang (no extension needed)\n./build-script     # #!/bin/bash\n./web-tool         # #!/usr/bin/env python3\n./cli-app          # #!/usr/bin/php\n\n# Files found by MIME type analysis\n./configure        # detected as shell script\n./setup            # detected as Python script\n```\n\n### Language-Specific Examples\n\n```bash\n# Find function definitions in Bash scripts\nbashgrep \"^function \" ~/scripts\n\n# Search for class declarations in PHP files\nphpgrep \"class [A-Z]\" ~/webproject\n\n# Find import statements in Python code\npygrep \"^import|^from.*import\" ~/python-projects\n\n# Search for TODO comments across all supported languages\nxgrep \"TODO:|FIXME:\" ~/development\n\n# Case-sensitive search for specific error handling\nbashgrep \"(?-i)ERROR\" ~/scripts\n\n# Search with file listing only\npygrep -l \"import requests\" ~/projects\n```\n\n### Advanced Usage\n\n```bash\n# Limit search depth and exclude specific directories\nxgrep -d 2 -X \"venv,node_modules\" \"api_key\" ~/projects\n\n# Reset exclusions and search everything\nbashgrep -X '' \"#!/bin/bash\" ~/\n\n# Use ripgrep options directly\nphpgrep --rg -C 3 -n \"class.*Controller\" ~/webapp\n\n# Debug mode to see what's happening\nxgrep -D \"pattern\" ~/code\n```\n\n## Configuration Options\n\n### Command-Line Options\n\n| Option | Description | Example |\n|--------|-------------|---------|\n| `-d, --maxdepth N` | Limit search depth | `-d 3` |\n| `-X, --exclude-dir DIR[,...]` | Exclude directories | `-X \"tmp,cache\"` |\n| `-D, --debug` | Show debug information | `-D` |\n| `-V, --version` | Display version | `-V` |\n| `--help` | Show help message | `--help` |\n| `--`, `--rg` | Pass options to ripgrep | `--rg -C 2 -n` |\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `XGREP_EXCLUDE_DIRS` | Override excluded directories | `.venv .git bak temp tmp .tmp .temp .Trash-0` |\n\n### File Detection\n\nThe tools intelligently detect files through:\n\n1. **Extensions**: `.sh`, `.bash` (Bash) • `.php`, `.phtml` (PHP) • `.py`, `.pyw` (Python)\n2. **Shebangs**: `#!/bin/bash`, `#!/usr/bin/php`, `#!/usr/bin/python3`, etc.\n3. **Exclusions**: Common build/dependency directories automatically skipped\n\n## Integration Examples\n\n### Git Hooks\n\n```bash\n# Pre-commit hook to find debugging statements\n#!/bin/bash\nif pygrep -q \"pdb\\.set_trace|breakpoint\\(\\)\" .; then\n    echo \"✗ Debugging statements found in Python files\"\n    exit 1\nfi\n```\n\n### Build Scripts\n\n```bash\n# Check for TODOs before release\nif xgrep -q \"TODO:|FIXME:\" src/; then\n    echo \"▲ Outstanding TODOs found\"\n    xgrep \"TODO:|FIXME:\" src/\nfi\n```\n\n### Development Workflow\n\n```bash\n# Find all error handling patterns\nbashgrep \"trap|set -e\" scripts/\nphpgrep \"try\\s*{|catch\\s*\\(\" src/\npygrep \"try:|except|raise\" app/\n```\n\n## Testing\n\nRun the comprehensive test suite:\n\n```bash\n# Run all tests\nmake test\n\n# Run specific test categories  \nmake test-unit\nmake test-integration\n\n# Verbose test output\nmake test-verbose\n```\n\nSee [TESTING.md](TESTING.md) for detailed testing information.\n\n## Contributing\n\nWe welcome contributions! Please see our [development guide](CLAUDE.md) for:\n\n- Development environment setup\n- Code conventions and style\n- Testing requirements\n- Pull request process\n\n### Quick Development Setup\n\n```bash\n# Clone and setup\ngit clone https://github.com/Open-Technology-Foundation/xgrep.git\ncd xgrep\n\n# Install development dependencies\nmake check-deps\n\n# Run linting and tests\nmake lint test\n```\n\n## Requirements\n\n- **Bash** 4.0+ (for associative arrays and modern features)\n- **ripgrep** (recommended for performance) or **grep** + **find**\n- **BATS** (for running tests)\n\n## Known Issues \u0026 Limitations\n\n- **Shebang Detection**: Limited by ripgrep's built-in file type definitions\n- **Symlink Handling**: Follows symlinks; may cause duplicate results in some cases\n- **Performance**: Fallback mode significantly slower than ripgrep on large codebases\n\nSee our [issue tracker](https://github.com/Open-Technology-Foundation/xgrep/issues) for current bugs and feature requests.\n\n## License\n\nThis project is licensed under the **GNU General Public License v3.0**. See [LICENSE](LICENSE) for details.\n\n## Author\n\n**Gary Dean** - Open Technology Foundation\n\n## Related Projects\n\n- [ripgrep](https://github.com/BurntSushi/ripgrep) - The fast search engine that powers xgrep\n- [ag (The Silver Searcher)](https://github.com/ggreer/the_silver_searcher) - Similar tool with different focus\n- [ack](https://github.com/beyondgrep/ack3) - Another grep alternative\n\n---\n\n**◉ Pro Tip**: Use `xgrep -D pattern directory` to see exactly how your search is being executed and what files are being examined.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-technology-foundation%2Fxgrep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-technology-foundation%2Fxgrep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-technology-foundation%2Fxgrep/lists"}