Substitute Command Flags

Analogy categoryAnalogies

Anatomy of the Substitute Command

The substitute command has the form s/regexp/replacement/flags. Everything after the final delimiter is a flag that modifies the behaviour of the replacement. Without any flag, sed replaces only the first match on each line the command touches, because the substitute command operates once per line by default. The flags are single characters (or, for the numeric flag, digits) placed directly after the closing delimiter, and several may be combined, such as s/foo/bar/gp.

🏏

Cricket analogy: The base s command is like a batsman facing just the first ball of an over and stopping; flags such as g are the instruction to keep playing every delivery in the over instead of walking off after ball one.

The g Flag and the Numeric Flag

The g (global) flag replaces every non-overlapping match on the line rather than just the first. A numeric flag N (any positive integer) replaces only the Nth match. The two can be combined: 2g means replace the second match and every match after it, effectively skipping the first occurrence and substituting from the second onward. This precise targeting is what makes sed capable of surgical edits, such as changing only the third comma-separated field without disturbing the others.

🏏

Cricket analogy: A numeric flag like 3 is a captain setting a fielder for the third ball specifically; 2g is telling the bowler to change tactics from the second delivery of the over onward while leaving the first as it was.

bash

# Replace only the FIRST occurrence per line (default)
echo 'red red red' | sed 's/red/blue/'      # blue red red

# Replace EVERY occurrence with the g flag
echo 'red red red' | sed 's/red/blue/g'     # blue blue blue

# Replace only the 2nd occurrence
echo 'red red red' | sed 's/red/blue/2'     # red blue red

# Replace the 2nd occurrence onward (2 + g)
echo 'red red red' | sed 's/red/blue/2g'   # red blue blue

Case-Insensitivity, Printing, and Writing

The i or I flag (GNU sed) makes the regular expression match without regard to letter case, so s/error/ok/i matches Error, ERROR, and error alike. The p flag prints the pattern space if a substitution was made, which is the standard idiom when combined with sed -n to emit only lines that were actually changed. The w filename flag writes the pattern space to the named file when a substitution succeeds, appending each matching line, which effectively filters and captures edited lines to disk in one pass.

🏏

Cricket analogy: The i flag is a fielder who catches a nick whether the ball comes off the bat's edge or face; p with sed -n is a highlights reel showing only the deliveries that produced a wicket.

Combine flags freely, but order the numeric flag before g: s/x/y/2g is valid, s/x/y/g2 is not. The p flag is most useful with sed -n, which suppresses the automatic printing so you see only the lines a substitution actually altered.

The i (case-insensitive) and I flags are GNU extensions and are not part of POSIX sed. On macOS/BSD sed they are unavailable, so a portable script must instead use a bracketed character class like s/[Ee][Rr][Rr][Oo][Rr]/ok/g. Test your scripts on the target platform before relying on GNU-only flags.

Flags follow the closing delimiter of s/regexp/replacement/ and change replacement behaviour.
With no flag, sed replaces only the first match on each affected line.
The g flag replaces every non-overlapping match on the line.
A numeric flag N replaces only the Nth match; N combined with g replaces from the Nth onward.
The i/I flag (GNU) makes matching case-insensitive; use bracket classes for POSIX portability.
The p flag prints the pattern space after a successful substitution, ideal with sed -n.
The w filename flag appends changed lines to a file, filtering and saving in one pass.