config

Manages a single key/value entry inside a config file — a flat keyvalue file or an INI file — touching only the line that defines the key and leaving every comment, blank line, and other key untouched. Idempotent: re-applying an unchanged declaration reports no change.

Category: Files & VCS

States

State	Meaning
`present`	The key equals `value` in the given section. An existing key’s value is replaced in place; a missing key (or section, or file) is created.
`absent`	Every line defining the key in the given section is removed; the section header is left in place even if it empties.

Parameters

Parameter	Type	Required	Description
`key`	string	yes	Config key to manage. Must not contain `=`, newlines, or start with `#`, `;`, or `[`.
`value`	string		Desired value (required for state `present`; rejected for `absent`). Numbers and bools are coerced to their string form; must be a single line.
`format`	string		File shape: `keyvalue` (flat `key=value` lines) or `ini` (with `[section]` headers). Default: `keyvalue`.
`section`	string		INI section header the key belongs to (`format: ini` only); `""` is the implicit top section before any header.
`space_around_separator`	bool		For newly written lines, emit `key = value` instead of `key=value`. Rejected for state `absent`. Default: `false`.
`create`	bool		For state `present`, create the file if it is missing. With `false`, a missing file is an error. Default: `true`.

Examples

Set a key in a flat keyvalue file

config:
  /etc/default/myapp:
    state: present
    key: LOG_LEVEL
    value: info

Set a key in an INI section

The section header is created if it does not exist.

config:
  /etc/myapp/app.ini:
    state: present
    format: ini
    section: server
    key: port
    value: "8080"
    space_around_separator: true

Remove a key, refusing to create a missing file

config:
  /etc/default/myapp:
    state: absent
    key: DEBUG
  /etc/myapp/optional.conf:
    state: present
    key: enabled
    value: "true"
    create: false

Notes

Distro-agnostic: operates on file text, not on any package or service.
Complements the file module — file owns whole-file content; config touches only one key’s line, preserving everything else.
Key matching is case-sensitive; present updates the first occurrence, absent removes all occurrences.
Out of scope in v0.1: TOML/YAML/JSON/XML formats, configurable separators, inline/trailing comments, uncomment-aware updates, repeated-key directives, and creating parent directories (planned, #107).

archive git