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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

#!/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