--- name: file-searching description: Regex file search via gh-grep extension. TRIGGERS - search code files, grep repository, file content search. --- # File Search with Regex **Capability:** Regex-based file content search across GitHub repositories using gh-grep **When to use:** Searching repository files (code, docs, configs) - NOT issues **Installation Required:** `gh extension install k1LoW/gh-grep` --- ## Key Distinction ``` ┌─────────────────────────────────────────────────────┐ │ SEARCH DECISION │ ├─────────────────────────────────────────────────────┤ │ │ │ gh search issues → Search ISSUES/PRs │ │ (searching-issues skill) │ │ │ │ gh grep → Search FILES (code, docs) │ │ (THIS skill) │ │ │ └─────────────────────────────────────────────────────┘ ``` --- ## Quick Commands ### Basic File Search ```bash # Search in repository gh grep "authentication" --owner myorg --repo myrepo # Search with regex gh grep "Bug.*critical" --owner myorg --repo myrepo # Search specific file types gh grep "API_KEY" --owner myorg --repo myrepo --include "*.env*" # Case-insensitive search gh grep -i "password" --owner myorg --repo myrepo ``` ### Common Patterns ```bash # Find function definitions gh grep "function.*login" --owner myorg --repo myrepo # Find TODO comments gh grep "TODO:" --owner myorg --repo myrepo --include "*.js,*.ts" # Find environment variables gh grep "process\.env\." --owner myorg --repo myrepo # Find imports gh grep "^import.*axios" --owner myorg --repo myrepo ``` --- ## Flags & Options ### Output Control ```bash # Show line numbers gh grep "error" --owner myorg --repo myrepo --line-number # Show file names only gh grep "config" --owner myorg --repo myrepo --files-with-matches # Limit results gh grep "api" --owner myorg --repo myrepo --max-count 10 ``` ### File Filtering ```bash # Include specific files gh grep "test" --owner myorg --repo myrepo --include "*.test.js" # Exclude files gh grep "console" --owner myorg --repo myrepo --exclude "node_modules/*" # Multiple file types gh grep "interface" --owner myorg --repo myrepo --include "*.ts,*.tsx" ``` ### Search Scope ```bash # Search specific branch gh grep "feature" --owner myorg --repo myrepo --branch develop # Search multiple repositories for repo in repo1 repo2 repo3; do gh grep "authentication" --owner myorg --repo $repo done ``` --- ## Regex Patterns ### Common Regex ```bash # Exact word match gh grep "\bpassword\b" --owner myorg --repo myrepo # Start of line gh grep "^export" --owner myorg --repo myrepo # End of line gh grep ";$" --owner myorg --repo myrepo --include "*.js" # Optional characters gh grep "colou?r" --owner myorg --repo myrepo # Character classes gh grep "[0-9]{3}-[0-9]{4}" --owner myorg --repo myrepo ``` ### Advanced Patterns ```bash # Function with any parameters gh grep "function \w+\(.*\)" --owner myorg --repo myrepo # Multiword match gh grep "error.*handler" --owner myorg --repo myrepo # Negation (find lines WITHOUT pattern) gh grep "import" --owner myorg --repo myrepo | grep -v "node_modules" ``` --- ## Common Workflows ### 1. Security Audit ```bash # Find hardcoded secrets gh grep "api_key.*=.*['\"]" --owner myorg --repo myrepo --include "*.js,*.ts,*.py" # Find password patterns gh grep -i "password\s*=\s*['\"][^'\"]+['\"]" --owner myorg --repo myrepo # Find environment variable leaks gh grep "AWS_SECRET" --owner myorg --repo myrepo ``` ### 2. Code Quality Check ```bash # Find TODO/FIXME comments gh grep -i "TODO|FIXME" --owner myorg --repo myrepo # Find console.log statements gh grep "console\.log" --owner myorg --repo myrepo --include "*.js,*.ts" # Find deprecated APIs gh grep "deprecated" --owner myorg --repo myrepo --include "*.md" ``` ### 3. Dependency Analysis ```bash # Find specific package usage gh grep "import.*lodash" --owner myorg --repo myrepo # Find external API calls gh grep "axios\.|fetch\(" --owner myorg --repo myrepo # Find database queries gh grep "SELECT.*FROM" --owner myorg --repo myrepo ``` ### 4. Documentation Search ````bash # Find markdown links gh grep "\[.*\]\(.*\)" --owner myorg --repo myrepo --include "*.md" # Find code examples in docs gh grep "^```" --owner myorg --repo myrepo --include "*.md" # Find heading references gh grep "^#{1,3} " --owner myorg --repo myrepo --include "*.md" ```` --- ## Multi-Repository Search ```bash #!/bin/bash # Search across multiple repositories PATTERN="authentication" OWNER="myorg" REPOS=("repo1" "repo2" "repo3") for repo in "${REPOS[@]}"; do echo "=== Searching $repo ===" gh grep "$PATTERN" --owner "$OWNER" --repo "$repo" --line-number echo "" done ``` --- ## Performance Considerations **Speed:** - gh-grep searches via GitHub API (network latency) - Faster than cloning repos for quick searches - Slower than local grep for large codebases **Rate Limits:** - GitHub API rate limits apply - Authenticated requests: 5,000/hour - Consider caching results for repeated searches **Best Practices:** 1. **Specific patterns** - Narrower regex = fewer results = faster 2. **File filters** - Use `--include` to reduce search scope 3. **Limit results** - Use `--max-count` for quick verification 4. **Batch searches** - Search multiple patterns in one pass --- ## Comparison: gh grep vs gh search issues | Feature | gh grep | gh search issues | | ---------------- | ---------------------- | ---------------- | | **Searches** | Repository files | Issues/PRs | | **Regex** | ✅ Full regex support | ❌ No regex | | **Wildcards** | ✅ Yes | ❌ No | | **Context** | ✅ Line-based | ❌ No context | | **File types** | ✅ Filter by extension | N/A | | **Installation** | Extension required | Native | | **Use case** | Code/docs search | Issue/PR search | --- ## Limitations - **No local search** - Always queries GitHub API - **Branch-specific** - Searches one branch at a time - **No multiline** - Pattern must match within single line - **Rate limits** - API quota applies - **No content display** - Shows matches, not full file content --- ## Tool Selection - **Search repository FILES** → Use `gh grep` (this skill) - **Search Issues/PRs** → Use `gh search issues` (searching-issues skill) - **AI-powered operations** → Use `gh models` (ai-assisted-operations skill) --- **Installation:** `gh extension install k1LoW/gh-grep` **Maintenance Status:** Actively maintained (211 stars, updated daily) **Full Extension Guide:** [GITHUB_CLI_EXTENSIONS.md](/docs/research/GITHUB_CLI_EXTENSIONS.md)