file.line

Manages a single line within a file: ensuring it is present, replacing it, inserting it at an anchor, or deleting it. Modeled after Salt's file.line module.

Source: pkg/state/modules/file_line.go

Parameters

Parameter	Type	Required	Default	Description
`name`	`string`	No	State ID	Absolute path to the target file. `path` is accepted as an alias. If both are omitted, the state ID is used as the path.
`content`	`string`	No	`""`	The desired line content.
`mode`	`string`	No	`ensure`	Operation: `ensure`, `replace`, `insert`, or `delete` (`absent` is a synonym for `delete`). Case-insensitive.
`match`	`string`	No	`""`	Expression identifying the target line. Treated as a Go regular expression; if it fails to compile, it falls back to a substring test. When empty, lines are matched by exact equality with `content`.
`before`	`string`	No	`""`	Regex/substring; when inserting, the line is placed before the first matching line.
`after`	`string`	No	`""`	Regex/substring; when inserting, the line is placed after the first matching line. Checked before `before`.

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

Mode Semantics

Mode	Behavior
`ensure` (default)	If a line matches (`match`, or exact `content` when `match` is empty), it is rewritten to `content` if different. If no line matches, `content` is inserted (at the `after`/`before` anchor, otherwise appended at the end).
`replace`	Every matching line that differs from `content` is rewritten. Nothing is inserted when no line matches.
`insert`	`content` is inserted (at the anchor or appended) only if no line already equals `content` exactly.
`delete` / `absent`	Every matching line is removed.

Check Behavior

If the file does not exist: ensure and insert report changes needed (the file will be created); replace and delete report no changes needed.
Otherwise, the transformation is computed in memory and the state reports changes only if the result differs from the current content.

Apply Behavior

If the file does not exist and the mode creates content (ensure/insert), the file is created containing just content and a trailing newline (mode 0644).
Otherwise the current content is read and stored as a backup, the line transformation is applied, and the result is written back with mode 0644. A trailing newline in the original file is preserved.
If the computed content is identical to the current content, Apply reports Changed: false.

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

# Ensure a specific sshd setting (replaces any existing PermitRootLogin line)
zester 'web-01' file.line /etc/ssh/sshd_config content='PermitRootLogin no' match='^PermitRootLogin'

# Delete matching lines
zester 'web-01' file.line /etc/hosts mode=delete match='old-hostname'

State File

Pin a config directive:

/etc/ssh/sshd_config:
  file.line:
    - content: "PermitRootLogin no"
    - match: "^PermitRootLogin"

Insert after an anchor line:

/etc/fstab:
  file.line:
    - mode: insert
    - content: "tmpfs /tmp tmpfs defaults 0 0"
    - after: "^# custom mounts"

Remove a line:

/etc/hosts:
  file.line:
    - mode: delete
    - match: "decommissioned-host"

Divergences from Salt

match falls back to a plain substring test when it is not a valid Go regular expression (Salt requires a valid Python regex).
Salt's location, quiet, indent, and backup parameters are not supported.

On this page