amber: a Rust search and replace tool with an interactive replacement prompt

One tool for finding and for changing text

amber is described in the README as a code search and replace tool written in Rust, inspired by ack and ag, the silver searcher, and other grep-like tools. That is an unusual position in the category. Most fast search tools answer one question, what matches this pattern, and leave the editing to sed, perl or a scripted find and xargs pipeline. amber folds both halves into one binary set and makes the editing half deliberately cautious.

The audience is developers working in a repository who need to rename a symbol, change a configuration value or update a literal across many files, and who would rather see each hit confirmed than have a regex rewrite applied silently to a working tree. The repository topics name the category directly: command-line-tool, grep, replace-text, search.

The implementation is Rust with an MIT licence, authored by dalance, and the package is published on crates.io as amber. The source layout is small and conventional, with src/ for the code, test/ for the test suite, benches/ for benchmarks, and two shell scripts named compare_ambs.sh and compare_ambr.sh that drive the published comparisons.

Two binaries and a prompt before every write

The package builds two binaries rather than one. Cargo.toml declares them separately, ambr with the path src/ambr.rs and ambs with the path src/ambs.rs, and the README explains the names: ambs means amber search and ambr means amber replace.

The four usage forms are the whole interface:

ambs keyword                  // recursively search 'keyword' from the current directory.
ambs keyword path             // recursively search 'keyword' from 'path'.
ambr keyword replacement      // recursively search 'keyword' from the current directory, and replace to 'replacement' interactively.
ambr keyword replacement path // recursively search 'keyword' from 'path', and replace to 'replacement' interactively.

Replacement is interactive by default. When the keyword is found, the tool stops and shows a prompt and waits:

Replace keyword? ( Yes[Y], No[N], All[A], Quit[Q] ):

Inputting y, Y or Yes replaces the keyword. Inputting a, A or All means replacing all keywords non-interactively, which is the escape hatch for the case where you have already decided and do not want to answer the prompt several hundred times. Q quits.

The trade is clear. A silent sed invocation finishes in one command and is completely reversible only by version control. amber trades that speed for a checkpoint on every match, and the All answer exists so that the checkpoint can be skipped when it is not wanted. For a repository with a clean history that is a good default; for a directory of generated files it is an interruption.

Large files are split and searched in parallel

The performance design is aimed at one specific shape of workload. The README states that large files, larger than 1MB by default, are divided and searched in parallel, and the Multi-threaded searching feature heading sits above that rule. Smaller files are handled in the ordinary way.

That is why the published benchmark has two halves that look contradictory, and why the tool is worth understanding before you benchmark it yourself. The dependency list supports the story: memmap maps files into memory so that the search does not read them through the ordinary file API, crossbeam provides the parallel primitives, and the sse feature is exposed as a Cargo feature and can be benchmarked separately through the Makefile target bench_sse, which runs cargo bench with the sse feature enabled.

The practical consequence is that amber is designed around the case of a single enormous file, such as a multi-gigabyte XML dump or a generated bundle, where a whole-file read is wasteful. On a tree of many small files, that advantage does not apply, and the numbers in the project's own comparison show amber behind ripgrep on exactly that pattern.

Installing from AUR, cargo or a release archive

Three installation routes are documented. On Arch Linux, the README points at the amber-search-git package in the AUR:

yay -S amber-search-git

The cargo route installs from crates.io:

cargo install amber

The manual route is a download from the release page, followed by extracting the binary into a directory on your PATH.

That is the whole setup. There is no daemon to run and no index to build, because the tool searches the filesystem as it walks it rather than maintaining a persistent index. The defaults already cover most cases: recursive search from the current directory, VCS directories ignored (.git,.hg,.svn and.bzr), binary files ignored, and colored output.

For developers working on the project itself, the Makefile shows the rest of the workflow. cargo test runs the suite, cargo bench runs the benchmarks, and there is a separate target that builds with the statistics feature enabled, cargo build --release with the statistics feature, which matches the statistics entry in the configuration file. Release builds are produced for several targets, including x86_64 and aarch64 Linux musl builds, a Windows MSVC build and both x86_64 and aarch64 macOS builds.

Sixteen TOML switches, and where the file lives

amber is configurable through a TOML file, and the README documents both the locations and the full set of entries. The paths are OS-specific. On Linux they are ~/.config/amber/ambs.toml and /etc/amber/ambs.toml, on macOS ~/Library/Preferences/com.github.dalance.amber/ambs.toml and /etc/amber/ambs.toml, and on Windows ~/AppData/Roaming/dalance/amber/config/ambs.toml. For compatibility, if ~/.ambs.toml exists it is preferred over the OS-specific locations.

The example above is for the ambs command, and ambr.toml in the same directory serves the ambr command, so the two commands are configured independently. The available entries and their defaults are:

regex          = false
column         = false
row            = false
binary         = false
statistics     = false
skipped        = false
interactive    = true
recursive      = true
symlink        = true
color          = true
file           = true
skip_vcs       = true

and the remaining entries continue:

skip_gitignore = true
fixed_order    = true
parent_ignore  = true
line_by_match  = false

Reading the defaults tells you what the tool does without being told. interactive is on, so replacement asks. recursive is on, so search walks the tree. skip_vcs and skip_gitignore are on, so version control metadata and ignored files are skipped, which is why a search from a repository root does not return results from build output. symlink is on, which means symlinked directories can lead the walk somewhere unexpected. Overriding is done by writing the single key you want to change, for example column = true.

The published benchmark, with its caveats

The README carries a full comparison, and it is worth reading the caveats along with the table. The environment is an Intel Xeon Gold 6134 at 3.20GHz with 1.5TB of memory on CentOS 7.5. The data is the Linux kernel repository with 52998 files and 2.2GB, and a single 8.5GB compressed Japanese Wikipedia XML file. The tool used for measurement is hyperfine with the option --warmup 3, described as loading all data into memory. The amber version measured is v0.5.1, which is older than the current v0.6.1.

In the search table, on the two patterns with many files, amber takes 212.8ms and 199.7ms against ripgrep at 154.1ms and 151.6ms, which puts amber at 139 percent and 132 percent of ripgrep. On the two patterns that are a large file with many matches and a large file with few matches, amber is the fastest at 1.068s and 1.027s, with ripgrep at 4.642s and 4.409s, or 434 percent and 429 percent of amber. grep is slower than amber on all four patterns.

The replace table compares against fastmod and the find plus sed pipeline. amber wins clearly on patterns 1, 3 and 4, at 792.2ms against 155724ms for find and sed on pattern 1, and 18.390s against 639.740s on pattern 3. On pattern 2 fastmod is slightly ahead, 352.4ms against amber's 418.1ms.

The honest summary is that amber's strength is large files and replacement, not many-file search, where another tool is ahead of it in the project's own numbers.

Where amber is the wrong tool

Several limits are visible in the documentation rather than hidden.

The first is that the search keyword is not a regular expression by default, and you have to add --regex to change that. This is deliberate, since a literal search is what most code searches want and a stray dot in a keyword should not silently match something else, but it also means the tool behaves differently from grep, where the pattern is a regular expression unless you escape it. The same applies to replacement, where regex captures become available only when --regex is enabled.

Second, the interactive prompt is on by default. For an automated script or a continuous integration step, that is a hang waiting to happen unless you pass --no-interactive, which the regex example in the README uses. Third, the configuration surface is only reachable through those sixteen documented entries, and the README does not describe a way to include or exclude files by glob or by extension, so a search over a mixed tree will still touch every text file it is allowed to read.

Fourth, the release history is irregular. The tagged versions are v0.6.1 on 2026-02-24, v0.6.0 on 2023-12-27 and v0.5.9 on 2021-04-06, and the last push was on 2026-10-14. The project is not archived and the code is being touched, but the tag line moved slowly, and the benchmark itself was run against v0.5.1 rather than the current release, so treat the published table as a snapshot of an older build.

Against running search and replacement as two separate steps

The alternative, and the one most people already have, is a search tool for finding and a separate editing tool for changing, joined by a shell pipeline. The README itself frames amber's replace mode against the traditional form of find piped into xargs sed, and the benchmark table quantifies that comparison: the find and sed pipeline takes 155724ms on pattern 1 where amber takes 792.2ms, and 639.740s on pattern 3 where amber takes 18.390s.

The difference in approach is where the safety check lives. In a pipeline, the list of files is produced first and the edit is applied to all of them, so a mistake in the pattern or the replacement lands everywhere at once and you recover with version control or not at all. amber interposes a prompt per match, so the decision to write is made with the match in front of you.

The cost is that amber gives up the composability of a pipeline. You cannot feed its output into another tool as easily as you can chain grep, because the search and the edit are two modes of the same program rather than two programs. And for the many-files search case, the benchmark shows amber behind ripgrep, so a setup that searches constantly and edits occasionally is better served by the dedicated search tool plus a careful editing step.

A third path is a scripted replacement in the language you already use, a script that walks the tree, matches, and writes. That is more code to own and test, but it is the only one of the three that can apply domain rules, such as skipping generated files or checking that a match sits in a test fixture.

Editorial conclusion

Adopt amber if you want one tool that both finds and replaces, and if you value the interactive confirmation before a replacement lands on a file. Do not adopt it as your only search tool if you search many small files often, since the project's own benchmark table shows amber slower than ripgrep on that pattern and faster only on very large files, and do not expect a steady release cadence from a project whose last tagged release was v0.6.1 on 2026-02-24. Verify first that the TOML settings you rely on are present in your version, since the configuration surface changed between releases, and read the README's note that the search keyword is a literal string by default unless --regex is passed.

Frequently asked questions

Official sources

1. dalance/amber on GitHub
2. Issues
3. License: MIT
4. README
5. Releases