Home

Awesome

amber

Actions Status Crates.io

amber is a code search and replace tool written by Rust. This tool is inspired by ack, ag, and other grep-like tools.

Features

Useful default settings

Multi-threaded searching

Large files ( > 1MB by default) are divided and searched in parallel.

Interactive replacing

amber can replace a keyword over directories (traditionally by find ... | xargs sed -i '...') . You can decide to do replacing or not interactively.

Installation

Arch Linux

Install the amber-search-git package from AUR.

yay -S amber-search-git

Cargo

You can install with cargo.

cargo install amber

Manual

Download from release page, and extract to the directory in PATH.

Usage

Two commands (ambs/ambr) are provided. ambs means "amber search", and ambr means "amber replace". The search keyword is not regular expression by default. If you want to use regular expression, add --regex.

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.

amber replace interactively by default. If the keyword is found, the following prompt is shown, and wait. If you input 'y', 'Y', 'Yes', the keyword is replaced. 'a', 'A', 'All' means replacing all keywords non-interactively.

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

If --regex option is enabled, regex captures can be used in replacement of ambr.

$ cat text.txt
aaa bbb
$ ambr --no-interactive --regex '(aaa) (?<pat>bbb)' '$1 $pat ${1} ${pat}' test.txt
$ cat text.txt
aaa bbb aaa bbb

Configuration

Configuration path

You can change configuration by writing a configuration file. The locations of the configuration file is OS-specific:

For compatibility, if ~/.ambs.toml exists, it will be preferred to the OS-specific locations.

The above paths are examples for the configuration of ambs command. ambr.toml in the same directory is used for ambr command.

Configurable value

Available entries and default values are below:

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
skip_gitignore = true
fixed_order    = true
parent_ignore  = true
line_by_match  = false

You can choose some entries to override like below:

column = true

Benchmark

Environment

Target Data

Pattern

Comparison Tools

Benchmarking Tool

hyperfine with the following options.

Result

patternamberripgrepgrep
1212.8ms ( 139% )154.1ms ( 100% )685.2ms ( 448% )
2199.7ms ( 132% )151.6ms ( 100% )678.7ms ( 448% )
31.068s ( 100% )4.642s ( 434% )3.869s ( 362% )
41.027s ( 100% )4.409s ( 429% )3.118s ( 304% )
patternamberfastmodfind/sed
1792.2ms ( 100% )1231ms ( 155% )155724ms ( 19657% )
2418.1ms ( 119% )352.4ms ( 100% )157396ms ( 44663% )
318.390s ( 100% )74.282s ( 404% )639.740s ( 3479% )
417.777s ( 100% )74.204s ( 417% )625.756s ( 3520% )