findir

Find & replace literal strings across file trees

v1.1.0

Install

curl -fsSL https://raw.githubusercontent.com/pubino/findir/main/findir \
  -o ~/.local/bin/findir && chmod +x ~/.local/bin/findir

Remove anytime with findir --self-remove

Literal means literal

No regex surprises. findir uses fixed-string matching so every character in your search is matched exactly as-is — dots, brackets, dollar signs, and all.

Replacing "foo" with "bar"

$ findir "foo" "bar" ./src

- football
+ bartball

- config.foo_value = "foo"
+ config.bar_value = "bar"

Every occurrence of the literal text "foo" is replaced — nothing more, nothing less.

Special characters? No escaping needed

$ findir "price ($USD)" "cost (EUR)" ./docs

- The price ($USD) is shown at checkout.
+ The cost (EUR) is shown at checkout.

Parentheses, dollar signs, dots — all matched literally. No backslash gymnastics.

Quick examples

Preview changes, then apply (default)

findir "old_func" "new_func" ./src

Apply immediately, skip preview

findir -y "old_func" "new_func" ./src

Dry run — preview only, no prompt

findir -n "TODO" "DONE" ./project

Filter by glob pattern and depth

findir --depth 2 -p "*.py" "os.path" "pathlib.Path" ./project

Case-insensitive search

findir -I "error" "warning" ./logs

Summary mode — list affected files only

findir --summary "old_api" "new_api" ./src

Interactive — confirm each file

findir -i "TODO" "DONE" ./docs

Restore from automatic backup

findir --restore .findir-backups/20260310-120000/manifest.txt

Options reference

Flag	Description
Arguments
`-s, --search STRING`	Search string
`-r, --replace STRING`	Replace string
`-d, --directory DIR`	Target directory (default: `.`)
Modes
`-n, --dry-run`	Preview only (no prompt to apply)
`-y, --yes`	Skip preview, apply changes immediately
`--summary`	List affected files only (no inline diffs)
`-i, --interactive`	Confirm each file before replacing
Filtering
`-I, --ignore-case`	Case-insensitive search
`-p, --pattern PATTERN`	Only process files matching glob pattern
`--depth N`	Limit directory traversal depth
Backup & Restore
`--backup-dir DIR`	Custom backup directory (default: `.findir-backups`)
`--restore FILE`	Restore from a backup manifest file
`--danger`	Skip backup creation
Output
`--no-color`	Disable colored output
`-v, --verbose`	Increase verbosity
`-q, --quiet`	Suppress non-error output
`--debug`	Enable debug output
Meta
`--self-update`	Update findir to latest version
`--self-remove`	Uninstall findir
`-V, --version`	Show version
`-h, --help`	Show help

Run findir --help for full details.

How it works

1 Discover files in the target directory, skipping binary files (detected via file --mime-encoding) and .git directories.
2 Match with grep -F — fixed-string matching, no regex interpretation. Every character in your search term is treated literally.
3 Preview changes as colored diffs. By default, findir shows you exactly what will change and asks before applying.
4 Replace with Perl quotemeta() for safe literal substitution. No special characters are interpreted during replacement.
5 Automatic backups before every change. Restore anytime with findir --restore and the manifest path shown in the summary.

Warning

findir performs destructive, in-place modifications to files. While it creates automatic backups by default, these backups are best-effort and should not be relied upon as your sole safety net.

Always maintain your own backups and use version control before running bulk find-and-replace operations. Preview changes with the default dry-run mode or -n before applying.

This software is provided "as is", without warranty of any kind, express or implied. The authors are not responsible for any data loss or damage resulting from its use. You are solely responsible for your data and backups.