STRING-REPLACE(1)

💅 STRING-REPLACE(1) — fish-shell's substring replacement era ✨

okay bestie, welcome to the string-replace page from the fish-shell manual. it's giving "find the substring, swap it, slay," and we're keeping every flag and every example exactly as advertised. 🫶

🌸 NAME 🌸

string-replace — replace substrings 💖

✨ SYNOPSIS ✨

string replace [-a | --all] [-f | --filter] [-i | --ignore-case]
               [-r | --regex] [(-m | --max-matches) MAX] [-q | --quiet]
               PATTERN REPLACEMENT [STRING ...]

💖 DESCRIPTION 💖

string replace is lowkey like string match, but instead of just matching, it replaces non-overlapping matching substrings with a replacement string and prints the result. By default, PATTERN is treated as a literal substring to be matched. no regex brain required unless you ask for it. 💅

If -r or --regex is given, PATTERN is interpreted as a Perl-compatible regular expression, and REPLACEMENT can contain C-style escape sequences like t as well as references to capturing groups by number or name as $n or ${n}. that's the regex girlie mode. ✨

If you specify the -f or --filter flag, then each input string is printed only if a replacement was done. This is useful where you would otherwise use this idiom: a_cmd | string match pattern | string replace pattern new_pattern. You can instead just write a_cmd | string replace --filter pattern new_pattern. literally fewer pipes, more main character energy. 🦋

If --max-matches MAX or -m MAX is used, string replace will stop all processing after MAX lines of input have matched the specified pattern. In the event of --filter or -f, this means the output will be MAX lines in length. This can be used as an "early exit" optimization when processing long inputs but expecting a limited and fixed number of outputs that might be found considerably before the input stream has been exhausted. early exit? we love a queen who knows when to leave the party. 👑

Exit status: 0 if at least one replacement was performed, or 1 otherwise.

also in the synopsis lineup: -a/--all, -i/--ignore-case, and -q/--quiet — they're all in the flag squad above, so don't forget them. 💖

🦋 EXAMPLES 🦋

🎀 Replace Literal Examples 🎀

>_ string replace is was 'blue is my favorite'
blue was my favorite

>_ string replace 3rd last 1st 2nd 3rd
1st
2nd
last

>_ string replace -a ' ' _ 'spaces to underscores'
spaces_to_underscores

🍓 Replace Regex Examples 🍓

>_ string replace -r -a '[^\d.]+' ' ' '0 one two 3.14 four 5x'
0 3.14 5

>_ string replace -r '(\w+)\s+(\w+)' '$2 $1 $$' 'left right'
right left $

>_ string replace -r '\s*newline\s*' '\n' 'put a newline here'
put a
here

📝 Copyright 📝

fish-shell developers

---

and that's the whole page, bestie. this absolute icon is from fish-shell version 4.9, dated Sep 08, 2026, manual STRING-REPLACE(1). periodt. 💅✨