RGR(1) | RGR(1) |
NAME
rgr - An interactive replacer for ripgrep that makes it easy to find and replace across files on the command line.
DESCRIPTION
In order to use this tool you must have first installed rg (AKA: ripgrep). See: https://github.com/BurntSushi/ripgrep/#installation.
USAGE
Normal Usage
Upon start all command line arguments are passed down to rg (adding --json and --no-config). The JSON output is then parsed, and you are presented with a terminal interface (described below).
Note since we use the --json flag, a number of rg's flags are unavailable. See rgr --help for a list of supported flags that will be sent through to ripgrep.
Capturing Groups
You may use capturing groups when using rgr, for example rgr "foo (\w+)". When using these, the matches can be used when replacing by referring to them as either their name $name or index $1. This syntax is inherited from the regex crate, 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).
Reading results from a file
This tool also supports reading results from a JSON file, with the following use case in mind:
INTERFACE
To see a list of keybindings, press ? while in the SELECT mode. There are a few different modes:
SELECT
REPLACE
CONFIRM
HELP
CONTROL CHARACTERS
The user may change how control characters are rendered in the interface by pressing control+v. The different modes are:
FILE ENCODING
Handling of file encoding happens in two places: the SELECT mode and when the replacements are written to disk.
In the SELECT mode, non UTF-8 bytes are shown with the UTF-8 replacement character. This occurs because the files themselves have not yet been read (the information is directly from ripgrep) and thus the encoding of the file is unknown.
During replacement encoding is handled in the following manner:
Note that 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.)
HOMEPAGE
BUGS AND FEATURES
Please report bugs and feature requests in the issue tracker. Do your best to provide a reproducible test case for bugs. Also please include the version of rgr and rg.
2023-12-18 |