How to Install and Use fastmod in Linux for Fast Codebase Search and Replace

Refactoring variables, renaming API endpoints, and updating configuration keys across large source code repositories can be stressful. Standard command-line tools like sed, awk, and perl execute destructive string replacements silently in the background, making it easy to introduce syntax regressions or alter unintended matches. fastmod is a fast, interactive search-and-replace utility written in Rust. It scans multi-file codebases, renders coloured terminal diffs for every proposed modification, and provides an interactive prompt allowing you to approve, reject, or batch-apply changes safely.

Why Use fastmod Instead of sed or codemod?

While traditional UNIX command pipelines require combining find, xargs, and sed -i, fastmod combines high-performance multithreaded directory traversal with interactive visual review:

• Visual Diff Previews: Shows exact line-by-line diffs with syntax colouring before writing to disk.
• Interactive Approvals: Prompt options allow approving individual edits (y), skipping matches (n), accepting all remaining matches across the file or project (a), or aborting cleanly (q).
• Multi-Line Matching: Matches complex multi-line patterns across line breaks without obscure regex hold-space manipulation.
• Full Regular Expression Support: Uses Rust’s high-speed regex engine with capture group substitutions ($1, $2).

Flag / Option	Command Syntax	Operational Purpose
Fixed Strings	-F, --fixed-strings	Treats regex special characters (., *, ?) as literal text.
Multi-line Regex	-m, --multiline	Enables regex patterns that span multiple lines.
File Extension Filter	--extensions js,ts,py	Restricts search and replace to specified file types.
Non-Interactive Execution	--accept-all	Executes all replacements automatically without interactive confirmation.
Hidden Files	--hidden	Includes dotfiles and hidden directory paths.

Installing fastmod on Linux

fastmod can be installed across modern Linux distributions using Rust’s package manager, Cargo, or by downloading precompiled release binaries.

Method 1: Installing via Cargo

If you have Rust and Cargo installed on your Ubuntu or Debian system:

sudo apt update && sudo apt install -y build-essential
cargo install fastmod

Ensure your Cargo binary directory is available in your system path by adding export PATH="$HOME/.cargo/bin:$PATH" to your ~/.bashrc or ~/.zshrc file.

Method 2: Installing Precompiled Binaries

To install directly without compiling from source:

curl -LO https://github.com/facebook/fastmod/releases/latest/download/fastmod-x86_64-unknown-linux-musl.tar.gz
tar -xzf fastmod-x86_64-unknown-linux-musl.tar.gz
sudo mv fastmod /usr/local/bin/
fastmod --version

1. Basic Interactive Search and Replace

The standard syntax for fastmod requires a search regex followed by the replacement string:

fastmod 'legacyUserEndpoint' 'modernAccountService'

When executed, fastmod traverses your working directory recursively, finds every matching file, and displays a coloured diff in your terminal:

• Red lines indicate text slated for deletion.
• Green lines indicate text that will be inserted.
• At the bottom prompt, press y to apply the change, n to skip to the next match, a to accept all remaining matches in the repository, or q to quit immediately.

2. Using Capture Groups for Structural Refactoring

Leverage standard regex capture groups inside parentheses to reorganize function arguments or refactor code structures:

fastmod 'getUserProfile((.*?),s*(.*?))' 'fetchAccountDetails($2, $1)'

In this example, $1 and $2 represent the first and second captured arguments, allowing you to invert parameter ordering across hundreds of source files in seconds.

3. Multi-Line Pattern Replacements

Refactoring code blocks that stretch across several lines is difficult in traditional tools. Pass the -m (or --multiline) flag:

fastmod -m 'try {s*doLegacyTask();s*} catch' 'try {
    doModernTask();
} catch'

This matches across newline boundaries while respecting indentation and bracket structures.

4. Filtering Targets by File Extension and Directory Path

To prevent fastmod from scanning compiled assets, documentation files, or build caches, restrict operations to specific extensions or paths:

fastmod --extensions py,pyi 'MAX_RETRIESs*=s*5' 'MAX_RETRIES = 10' ./src/services/

By default, fastmod respects your repository’s .gitignore rules, ensuring that dependencies like node_modules/ or virtual environments like .venv/ are automatically excluded.

Best Practices and Operational Safety

• Always Commit to Git First: Ensure your git working tree is clean (git status) before running codebase refactoring. If you make an erroneous replacement, you can revert all edits instantly with git restore . or git reset --hard.
• Use Literal Flags for Special Characters: If searching for strings containing dots, asterisks, or brackets (such as config.server.url), pass the -F flag to avoid escaping every character with backslashes.
• Batch Execution in CI/CD Scripts: When automating refactoring tasks in shell scripts or deployment pipelines, pass --accept-all to run non-interactively without waiting for user keyboard input.