# Comparison

sgrep fits into the ecosystem of code search tools. This page compares it to popular alternatives and explains when to use each.

## Feature Comparison Matrix

| Feature | sgrep | grep | ripgrep | ag | ast-grep | CodeQL |
|---------|-------|------|---------|----|----------|---------|
| **Search Type** | Semantic | Text | Text | Text | AST | Semantic |
| **Offline** | Yes | Yes | Yes | Yes | Yes | Partial |
| **Zero Setup** | Yes | Yes | Yes | Yes | No | No |
| **Binary Size** | ~8MB | ~300KB | ~1MB | ~500KB | ~10MB | SDK |
| **Speed** | Fast | Fast | Fastest | Fast | Medium | Slow |
| **Language Agnostic** | Yes | Yes | Yes | Yes | No* | No |
| **Cross-language** | Yes | Yes | Yes | Yes | Yes | No |
| **Understanding Meaning** | Yes | No | No | No | Partial | Yes |
| **JSON Output** | Yes | No | No | No | Yes | Yes |
| **API Calls** | None | None | None | None | None | Optional |

*ast-grep supports many languages but requires language-specific grammars.

## Tool Deep Dives

### grep

The original Unix text search tool.

**Strengths:**
- Ubiquitous (installed everywhere)
- Predictable exact matching
- Regex support
- Zero learning curve

**Weaknesses:**
- No semantic understanding
- Slow on large codebases
- Limited to literal text patterns

**Use when:** You need exact text matching, working on unfamiliar systems, or searching non-code files.

```bash
# Find exact string
grep "TODO" src/

# grep can't do this
sgrep "future improvements needed"  # Finds "TODO", "FIXME", etc.
```

### ripgrep (rg)

Modern, Rust-based grep replacement.

**Strengths:**
- Extremely fast (parallel search)
- Smart filtering (respects .gitignore)
- Great defaults
- PCRE regex support

**Weaknesses:**
- Still text-based (no semantics)
- Can't understand synonyms or related concepts

**Use when:** You need fast literal search with great UX.

```bash
# ripgrep is faster for exact text
rg "Error" src/

# But misses related concepts
sgrep "error handling"  # Finds "Error", "Exception", "fail", etc.
```

### the_silver_searcher (ag)

Early contender in fast grep tools.

**Strengths:**
- Faster than grep
- Respects .gitignore
- Clean output format

**Weaknesses:**
- Less actively maintained than ripgrep
- No semantic search

**Use when:** You have existing ag scripts or prefer its output format.

### ast-grep

AST-based code search with structural matching.

**Strengths:**
- Understands code structure
- Pattern matching on AST nodes
- Language-specific queries
- Refactoring support

**Weaknesses:**
- Requires language parsers
- Not truly semantic (matches structure, not meaning)
- Heavier setup

**Use when:** You need structural code matching or automated refactoring.

```bash
# ast-grep matches structure
sg -p 'console.log($_)' src/

# sgrep matches meaning
sgrep "logging statement"  # Finds console.log, logger.info, print, etc.
```

### CodeQL

Powerful semantic analysis framework from GitHub.

**Strengths:**
- Deep semantic understanding
- Taint analysis
- Vulnerability detection
- Extensive query library
- Data flow analysis

**Weaknesses:**
- Heavy setup (database generation)
- Slow (not for quick search)
- Language-specific databases
- Not ideal for ad-hoc queries

**Use when:** You need deep security analysis or complex vulnerability scanning.

```bash
# CodeQL for security analysis
codeql database analyze --run=security-queries

# sgrep for quick semantic search
sgrep "security vulnerability" src/
```

## When to Use sgrep

### sgrep excels when:

1. **You don't know exact terms**
   ```bash
   # Find database code without knowing ORM name
   sgrep "database query" src/
   ```

2. **Cross-language search**
   ```bash
   # Find auth code across Python, Rust, and TypeScript
   sgrep "authentication" src/
   ```

3. **Exploring unfamiliar codebases**
   ```bash
   # Understand what modules exist
   sgrep "data processing" src/
   ```

4. **Code review automation**
   ```bash
   # Check for similar patterns
   sgrep --json "potential bug" src/ | jq .
   ```

5. **Quick semantic queries**
   ```bash
   # Faster than setting up CodeQL
   sgrep "memory leak pattern" src/
   ```

### When to use other tools:

| Task | Use This Tool |
|------|---------------|
| Exact string search | grep / ripgrep |
| Regex matching | ripgrep |
| Structural refactoring | ast-grep |
| Security audit | CodeQL |
| Performance profiling | ripgrep (faster) |
| Semantic exploration | sgrep |

## Hybrid Workflow

The best approach often combines tools:

```bash
# Fast pre-filter with ripgrep, then semantic
rg "error" src/ -l | xargs sgrep "error handling"

# Use sgrep to find patterns, CodeQL for deep analysis
sgrep "sql injection" src/  # quick scan
codeql analyze src/  # thorough audit
```

## Key Differentiators

### Meaning Over Text

Traditional tools search for what you type. sgrep searches for what you mean.

```
Query: "database connection"

grep finds:
- "database connection" (exact match only)

sgrep finds:
- "db.connect()"
- "open_database()"
- "ConnectionPool::new()"
- "psql://localhost"
- "MongoClient()"
```

### Language Independence

Learn one query language for all programming languages:

```bash
# Works for Python, Rust, Go, JavaScript...
sgrep "async function" src/
```

### Offline First

No API calls, no rate limits, no data leaving your machine:

```
Model: ~7.5MB (downloaded once, cached locally)
Inference: Runs on your CPU
Privacy: Code never leaves your computer
```

### Developer Experience

```bash
# Familiar grep-like interface
sgrep "pattern" path/

# JSON for pipelines
sgrep --json "pattern" | jq .

# Hybrid mode (BM25 + semantic)
sgrep --hybrid "pattern" path/
```

## Benchmarks

On a codebase of 100K lines of code:

| Operation | sgrep | ripgrep | CodeQL |
|-----------|-------|---------|--------|
| First run | 15s | 0.5s | 5min |
| Subsequent (cached) | 10ms | 0.5s | 30s |
| "find auth code" | Works | Misses many | Works |
| "function_name" | Works | Works | Works |

sgrep's strength is in semantic queries, not raw text search speed.

## Summary

- **grep**: The universal baseline
- **ripgrep**: Fastest literal search
- **ast-grep**: Structural code matching
- **CodeQL**: Deep security analysis
- **sgrep**: Fast semantic search

Use sgrep when you need to search by meaning, not just text. Combine with other tools for the best workflow.