file.replace

Performs a regular-expression search-and-replace within a file, with optional append/prepend when the pattern is not found. Modeled after Salt's file.replace module.

Source: pkg/state/modules/file_replace.go

Parameters

Parameter	Type	Required	Default	Description
`name`	`string`	No	State ID	Absolute path to the target file. `path` is accepted as an alias.
`pattern`	`string`	Yes	—	Go regular expression to search for. Compiled with the `(?m)` flag, so `^` and `$` anchor per line (matching Salt's `re.MULTILINE` default).
`repl`	`string`	No	`""`	Replacement text. Backreferences are expanded using Go syntax: `$1`, `${name}`.
`count`	`int`	No	`0`	Maximum number of replacements. `0` replaces all matches.
`append_if_not_found`	`bool`	No	`false`	Append `not_found_content` (or `repl`) at the end of the file when the pattern does not match.
`prepend_if_not_found`	`bool`	No	`false`	Prepend `not_found_content` (or `repl`) at the start of the file when the pattern does not match.
`not_found_content`	`string`	No	`repl`	Content used for append/prepend when the pattern is not found.

All states also accept the full set of requisite parameters and Salt-parity state attributes — see Dependencies & Requisites.

Check Behavior

The replacement is computed in memory and the state reports changes only if the result would differ from the current content:

Pattern matches — changes are needed when the replaced output differs from the file.
Pattern does not match — changes are needed only when append_if_not_found or prepend_if_not_found is set and the fallback content is not already present in the file.
File does not exist — changes are needed only when append_if_not_found or prepend_if_not_found is set (the file will be created with the fallback content).

Apply Behavior

Reads the file (stored as a backup for revert).
If the pattern matches, replaces matches (respecting count), expanding $1/${name} backreferences.
If the pattern does not match and append/prepend is enabled, adds not_found_content (defaulting to repl) at the end/start, with newline separators ensured. If the content is already present verbatim, nothing is done.
Writes the result back with mode 0644.

Revert Behavior

If the file did not exist before Apply, it is removed.
Otherwise the original content is restored from the backup.

Examples

Direct Execution

# Rewrite a config directive
zester 'web-01' file.replace /etc/ssh/sshd_config pattern='^#?PasswordAuthentication.*' repl='PasswordAuthentication no'

State File

Replace a directive, appending it when absent:

/etc/ssh/sshd_config:
  file.replace:
    - pattern: "^#?PasswordAuthentication.*"
    - repl: "PasswordAuthentication no"
    - append_if_not_found: true

Limit to the first match, using a backreference:

/etc/myapp.conf:
  file.replace:
    - pattern: "listen_port = (\\d+)"
    - repl: "listen_port = 8443  # was ${1}"
    - count: 1

Divergences from Salt

Backreferences in repl use Go's $1 / ${name} syntax, not Python's \1 / \g<name>.
The pattern is a Go (RE2) regular expression — no lookaheads/lookbehinds.
Salt's flags, ignore_if_missing, backup, and dry_run parameters are not supported. The MULTILINE flag is always on (which is also Salt's default).

On this page