Writing idempotent admin scripts: check-then-change, drop-in files and marker comments

Goal

Make an admin script safe to re-run: applying it twice produces the same end state as applying it once, with no duplicated lines, no repeated package installs, and no error on the second run.

Prerequisites

Read access to the current state of whatever the script changes (file, package, registry key, service); a way to write files atomically (write to a temp path, then move/rename).

Steps

1. Check before you change. Before adding a line, creating a user or installing a package, query whether it already exists and compare to the desired value. In bash: grep -qxF -- "$line" "$file" || printf '%s\n' "$line" >> "$file". In PowerShell: if (-not (Get-LocalUser -Name $name -ErrorAction SilentlyContinue)) { New-LocalUser $name ... }. Skip the change entirely when the check already matches; do not rely on the underlying command failing gracefully on a repeat.
2. Prefer a drop-in file over editing a shared one. Where the target supports it (systemd units read a <name>.d/*.conf drop-in directory and merge those files, in the manual's words, "in the alphanumeric order" after the main unit; sudoers reads /etc/sudoers.d/*; many daemons read an include directory), write or replace your own whole file instead of searching-and-editing someone else's. Re-running the script overwrites only that one file, never accumulating duplicate edits inside a file you do not own. A systemd drop-in takes effect only after systemctl daemon-reload; a sudoers drop-in must pass visudo -cf <file> before it is moved into place, because a syntax error there can break sudo for everyone, and files whose names contain a dot are ignored.
3. When you must edit a shared file, bound your edit with marker comments. Wrap the block you own between recognisable markers, e.g. # BEGIN managed-by-agent-x / # END managed-by-agent-x, and on each run replace everything between the markers rather than appending. This keeps the edit idempotent and cleanly removable.
4. Write new content to a temp file and rename it into place (mv on POSIX, Move-Item -Force after Set-Content -Path $tmp on Windows, which is not guaranteed atomic) rather than editing in place, so a run interrupted mid-write cannot leave a half-written config behind. Create the temp file in the target's directory (a rename is atomic only within one filesystem) and set owner and mode before the rename: mktemp creates files with mode 0600.
5. Make destructive steps conditional on the check, not on "first run". A "first run" sentinel can diverge from the real state (a hand edit, a partially failed run); test the target itself.
6. Log what changed versus what was already correct, so a re-run's log clearly shows "0 changes made" rather than looking identical to a first successful run.

Expected result

Running the script N times leaves the same end state as running it once; the log from a repeat run shows no-op checks rather than repeated writes; a partially failed run can simply be re-run.

Limits and test basis

Idempotency covers the script's own writes; it does not protect against another process or administrator changing the same file concurrently — pair it with the locking pattern for concurrent runs. Marker-comment editing only works for text formats where comments are safe to add; binary or strict-schema config formats need the drop-in approach instead.