📜 Training Arc — Chapter 1

Getting Started

From zero to sub-millisecond search in under 5 minutes. No configuration files. No daemons to set up manually. Just build and go.

01 Prerequisites

✓ Rust toolchain (stable) — rustup toolchain install stable
✓ Cargo (comes with Rust)
✓ A terminal and a project to search through

02 Installation

Clone the repository and build the release binary. Then copy it to a location in your PATH.

installation

# Clone and build
git clone https://github.com/kevinbdx35/instant-grep
cd instant-grep
cargo build --release

# Copy to PATH (adjust path as needed)
cp target/release/ig ~/.local/bin/ig

# Verify installation
ig --version

ℹ

Tip: Make sure ~/.local/bin is in your $PATH. Add export PATH="$HOME/.local/bin:$PATH" to your shell config if needed.

03 Build your first index

Navigate to any project directory and run ig index. This creates a .ig/ directory with three binary files: lexicon.bin, postings.bin, and metadata.bin.

build index

❯ ig index .

◆ Gathering chakra... scanning directory tree
◆ Skipping 38 excluded directories (node_modules, target, .git, ...)
◆ Building sparse n-gram index: 1,247 files
✓ Index built in 147ms
   lexicon:  2.1 MB  (.ig/lexicon.bin)
   postings: 0.2 MB  (.ig/postings.bin)
   metadata: 0.0 MB  (.ig/metadata.bin)

lexicon.bin

Hash table mapping n-grams to posting list offsets

postings.bin

Sorted file ID lists for each n-gram

metadata.bin

File paths, modification times, version info

04 Your first search

Run ig with any regex pattern. If no index exists, it will build one automatically — the auto-build jutsu.

⚡

Shortcut: ig "pattern" is equivalent to ig search "pattern". The search subcommand is optional — ig searches by default.

first search

# Basic search
ig "async fn" src/
src/daemon.rs:23:    pub async fn handle_connection...
src/query/mod.rs:7:     pub async fn run(...)

# Case-insensitive search
ig -i "TODO" .

# With context lines
ig -C 3 "Result<T>" .

# JSON output for AI agents
ig --json "impl Trait" .

# Filter by file type
ig --type rs "pub fn" .

05 Auto-build explained

When you run ig search, it checks if a .ig/ index exists in the target directory. If not, it automatically runs ig index first. This means you can always just run search — no manual indexing required.

1 ig "pattern" . called (or ig search "pattern" .)

2 Check for .ig/metadata.bin — if missing, build index first

3 Extract n-grams from regex, query posting lists, verify matches

✓ Results printed in ~0.9ms

Next steps

⚡