Finf - A Fast, Self-Contained File Searcher with Contextual Previews

Finf: A Fast, Self-Contained File Searcher with Contextual Previews

If you are a pro developer, at some point you may have desired to search multiple files while also being able to see context around the match. Enter finf, a tiny but mighty search tool that combines ripgrep, fzf, and bat, all in one self-contained Zsh function.

What it Does

finf lets you:

• Search for a pattern across your project using rg (ripgrep).
• Interactively browse matches with fzf.
• Preview matches in context with bat, centered on the line that matched.
• Handle file names with spaces or special characters safely.

All this without requiring an external script or complex setup.

---

The Implementation

Here’s the complete Zsh function which you can place in your .zshrc:

finf() {
  rg --no-heading --line-number --follow "$@" 2>/dev/null |
  fzf -d: --with-nth=1,2 --preview '
    file=$(echo {} | cut -d: -f1)
    line=$(echo {} | cut -d: -f2)
    height=${FZF_PREVIEW_LINES:-40}
    start=$(( line - height / 2 ))
    (( start < 1 )) && start=1
    end=$(( start + height ))
    bat --style=plain --color=always -H "$line" -r "$start:$end" --pager=never -- "$file"
  '
}

How It Works

1. Search with rg: rg outputs lines in the form file:line_number:match. The --no-heading and --line-number options make the output easy to parse.
2. Interactive selection with fzf: fzf allows you to scroll through results. The --with-nth=1,2 option ensures we correctly separate the file path and line number.
3. Contextual preview with bat: The preview script extracts the file and line number from the selected result. It calculates a preview range that centers the match in the middle of the preview window, defaulting to 40 lines. bat highlights the matching line while showing surrounding lines for context.
4. Robust handling of filenames: By extracting the file path safely and quoting it properly, this function works even with filenames that contain spaces or special characters.

---

Usage Examples

finf TODO
finf -g "*.sh" main finf "deploy"

The selected match will show a highlighted preview, perfectly centered in the window, letting you quickly understand the surrounding code without opening the file in an editor.

---

Why It’s Awesome

• Vulcanized: Self-contained; no external scripts required.
• Interactive: Fast navigation through hundreds of matches.
• Context-aware: See the match in surrounding lines, not just the line itself.
• Safe: Works with spaces and special characters in filenames.

If you’re tired of grep | less or rg | head -n, finf is a modern, minimal, and highly effective tool for searching code from the terminal.

---

💡 Tip: You can customize the preview height by setting the environment variable:

export FZF_PREVIEW_LINES=30

This will adjust how many lines bat shows around the match.

---

Sample output of finf in action:

finf message

Inspiration for this post came from Charles Thomas’s blog on lightning-fast code search.