RGR(1)

💅 RGR — like, the interactive replacer for ripgrep, bestie

okay so picture this: you're on the command line, you've got a million files, and you need to find-and-replace across all of them. That's rgr, and it's lowkey the most iconic little tool in the RGR(1) manual. She's giving find-and-replace, but make it ✨interactive✨. Let's get into it 🫶

---

🌸 NAME 🌸

rgr — an interactive replacer for ripgrep that makes it easy to find and replace across files on the command line. Fr fr, that's the whole vibe.

---

🎀 DESCRIPTION 🎀

Bestie, real talk: before you can even look at this tool, you gotta have installed rg (AKA: ripgrep) first. No rg, no rgr, periodt. Install deets live here: https://github.com/BurntSushi/ripgrep/#installation 💖

---

🌈 USAGE 🌈

✨ Normal Usage ✨

So when you start her up, literally all your command line arguments get passed down to rg — and she sneaks in --json and --no-config on top, no cap. Then the JSON output gets parsed, and boom, you're looking at a whole terminal interface (the deets are below, keep scrolling 👀).

Heads up bestie: because we're using the --json flag, a bunch of rg's flags are just, like, unavailable. Not me gatekeeping — that's just how it is. Run rgr --help to see the list of supported flags that actually get sent through to ripgrep 🙈

🦋 Capturing Groups 🦋

You can absolutely use capturing groups with rgr, like this:

rgr "foo (\w+)"

When you do that, you can use the matches while replacing by referring to them either by their name $name or their index $1. This syntax is inherited from the regex crate, iykyk — see: https://docs.rs/regex/1.8.4/regex/struct.Captures.html#method.expand

⚠️ Only one pattern may be passed at a time when capturing groups are used (i.e., multiple -e <pat> flags are not allowed). One pattern. That's the rule. 💅

⭐ Automatic replacement ⭐

Got no time for the interface? Pass -y or --autoreplace together with -r or --replace and she'll replace every match without ever opening the interactive interface. Iconic. For example:

rgr -y "old_name" -r "new_name"

The replacement must be supplied explicitly — like, you can't just be vague about it. Automatic replacement exits with an error before even searching if -r or --replace is missing. Vibe check failed, no search for you 😭

🍓 Reading results from a file 🍓

Bestie, she also supports reading results from a JSON file, and here's the use case she had in mind:

1. The user runs rg --json <args> > rg-results.json
2. Now, this tool can be run with those results via RGR_JSON_FILE=./rg-results.json rgr

Look at that workflow. Main character energy, honestly 👑

---

💜 INTERFACE 💜

To see a list of keybindings, press ? while you're in the SELECT mode. There are a few different modes, so let's meet the cast 🎬

🌸 SELECT 🌸

• This mode is the first mode presented after rgr is started. She's the opener, the one who walks in first 💅
• In this mode a list of matches is presented, and they can be toggled on or off.
• Toggling a match off means that the match itself will not be replaced. Simple as that.

🦋 REPLACE 🦋

• In this mode the user types the desired replacement text and the matches are updated in real-time. So satisfying to watch ngl.
• Note that this is a demo only — no changes are written to disk. It's giving preview, not commitment 🙈
• Non UTF-8 bytes in the matches are shown with the UTF-8 replacement character in this mode.
• Pressing Ctrl+s will cause all selected matches to be replaced with the text entered.

⭐ CONFIRM ⭐

• Prompt the user to confirm before writing replacements to disk. Consent matters, bestie ✨
• Replacements are written to disk, and all attempts to use the correct file encoding are made. (see FILE ENCODING.)
• Note that rgr will not replace a different slice of bytes than what rg reported in its output. (see FILE ENCODING.) She's careful like that.

💖 HELP 💖

• This mode provides information about rgr and its keybindings. When in doubt, press the help button, that's the rule 🫶

---

🧚 CONTROL CHARACTERS 🧚

You can change how control characters are rendered in the interface by pressing Ctrl+v. The different modes are:

• C: show common control characters
• c: show common control characters (one line)
• A: show all control characters
• a: show all control characters (one line)
• H: show common control characters as spaces, and strip others (hidden)

Capital letters vs lowercase letters — she's detail-oriented, we love her for it 💅

---

🔥 FILE ENCODING 🔥

Handling of file encoding happens in two places: the SELECT mode and when the replacements are written to disk. Two whole places. She's thorough.

In the SELECT mode, non UTF-8 bytes are shown with the UTF-8 replacement character. Why? Because the files themselves have not yet been read — the information is directly from ripgrep — and thus the encoding of the file is unknown. She's working off secondhand info, give her a break 😭

During replacement, encoding is handled in the following manner:

• If a BOM (Byte Order Mark) is found, then that encoding is used, otherwise
• If an encoding was passed to ripgrep, then that encoding is used, otherwise
• The chardet (https://github.com/thuleqaid/rust-chardet) library is used to detect the encoding
• If that fails, then UTF8 is assumed

⚠️ Okay this part is important, so listen up: rgr will never replace a match that it doesn't expect. If, when replacing a match, the bytes to replace do not match those matched by ripgrep, then the tool will bail out and the file will not be written. (Errors will be reported to STDERR.)

Like, she'd rather give up than get it wrong. Respect honestly 🙌

---

🌟 HOMEPAGE 🌟

https://github.com/acheronfail/repgrep

Go give her a star, she deserves it ⭐

---

💀 BUGS AND FEATURES 💀

Please report bugs and feature requests in the issue tracker. Do your best to provide a reproducible test case for bugs — the more reproducible the better, bestie, we're begging 🥺 Also please include the version of rgr and rg. Both of them. Don't make her guess.

---

and that's the whole manual, you're officially caught up 💖 this page was brought to you by RGR(1), dated 2026-09-02 — mwah, go forth and replace things responsibly 🎀✨