rg — Search and Replace

Search and Replace Preview

rg’s -r flag performs replacement on output only — it never modifies files. This makes it a safe dry-run tool for refactoring. Combine with --passthru to see full file context, or redirect to create a modified copy.

Basic replacement preview — swap pattern in output

cat <<'EOF' > /tmp/rg-replace-test.adoc
= Old Title
:description: An old description
:navtitle: Old Nav

Old content with old references.
EOF
rg 'Old' -r 'New' /tmp/rg-replace-test.adoc

Only matching lines appear with the replacement applied. The file on disk is untouched. Think of -r as sed 's/old/new/' but without -i — preview mode by default.

Capture group replacement — extract and reshape with -Po and -r

cat <<'EOF' > /tmp/rg-captures.adoc
xref:codex/rg/basics/index.adoc[Basics]
xref:codex/rg/regex/index.adoc[Regex]
xref:codex/rg/output/index.adoc[Output]
EOF
rg -Po 'xref:codex/rg/(\w[\w-]*)/index\.adoc\[([^\]]+)\]' -r 'Discipline: $1 — Label: $2' /tmp/rg-captures.adoc

-P enables PCRE2 for full capture group support. -o prints only the matched portion. $1 and $2 refer to the first and second capture groups. Without -o, the entire line prints with the matched region replaced.

Named capture group replacement — self-documenting extractions

cat <<'EOF' > /tmp/rg-named.adoc
:ad-dc-ip: 10.50.1.50
:ise-pan-ip: 10.50.1.20
:pfsense-ip: 10.50.1.1
EOF
rg -P ':(?P<attr>[\w-]+):\s+(?P<val>\S+)' -r 'attribute="${attr}" value="${val}"' /tmp/rg-named.adoc

Named groups (?P<name>…) replace with ${name} in the replacement string. Clearer than positional $1/$2 when patterns have many groups.

--passthru for full file context with replacements highlighted

cat <<'EOF' > /tmp/rg-passthru.conf
# Server config
listen 80;
server_name example.com;
listen 443 ssl;
root /var/www/html;
EOF
rg 'listen 80' -r 'listen 8080' --passthru /tmp/rg-passthru.conf

--passthru prints every line from the file. Non-matching lines pass through unchanged; matching lines show the replacement. This gives you diff-like context without a separate tool.

Replace + redirect — create a modified copy without touching the original

cat <<'EOF' > /tmp/rg-original.adoc
= WRKLOG-2026-04-10
:description: Thursday worklog
:navtitle: April 10
EOF
rg 'April 10' -r 'April 11' --passthru /tmp/rg-original.adoc > /tmp/rg-modified.adoc
diff /tmp/rg-original.adoc /tmp/rg-modified.adoc

--passthru + redirect is the rg equivalent of sed 's/…/…/' file > newfile. The original is preserved; the modified version goes to a new path.

Practical — preview xref path renaming across AsciiDoc files

rg -n 'codex/rg/output/' -r 'codex/rg/output-modes/' ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/pages/codex/rg/ 2>/dev/null || echo "No matches — path already migrated or never existed"

Before running sed -i for a bulk rename, use rg -r to preview what the replacement looks like in context. The -n flag adds line numbers so you know exactly where changes would land.

Practical — transform attribute format in preview

cat <<'EOF' > /tmp/rg-attrs.adoc
The server IP is 10.50.1.50 and the gateway is 10.50.1.1.
DNS runs on 10.50.1.50 port 53.
EOF
rg -Pn '10\.50\.1\.50' -r '{ad-dc-ip}' --passthru /tmp/rg-attrs.adoc

Preview what a hardcoded IP looks like after conversion to an AsciiDoc attribute. Run across your entire docs tree to estimate the scope of an STD-019 remediation.

Compare original vs replaced — diff with process substitution

cat <<'EOF' > /tmp/rg-diff-test.adoc
= Infrastructure Overview
:description: Network infrastructure documentation

The DNS server at 10.50.1.50 handles all queries.
The firewall at 10.50.1.1 routes traffic.
ISE at 10.50.1.20 manages authentication.
EOF
diff <(cat /tmp/rg-diff-test.adoc) <(rg '10\.50\.1\.50' -r '{ad-dc-ip}' --passthru /tmp/rg-diff-test.adoc)

Process substitution <(…) feeds two streams into diff without temp files. The left side is the original; the right side is the rg replacement preview. Non-zero exit from diff means changes exist.

Multi-pattern replacement — chain rg calls with pipe

cat <<'EOF' > /tmp/rg-multi.adoc
Connect to 10.50.1.50 for DNS.
Firewall is 10.50.1.1 on VLAN 10.
EOF
rg '10\.50\.1\.50' -r '{ad-dc-ip}' --passthru /tmp/rg-multi.adoc | rg '10\.50\.1\.1' -r '{pfsense-ip}' --passthru

rg processes stdin when no file argument is given. Chaining --passthru replacements creates a multi-step transformation pipeline. For actual file modification, use sed -i with multiple -e expressions instead.