Idempotency and Convergent Shell Operations

1. Idempotency means repeatable intent

An idempotent automation step can run more than once and still converge on the same intended state. The second successful run should not create duplicates, corrupt data, or produce a different result merely because the first run already succeeded.

flowchart LR
  D["desired state"] --> C{"current state matches?"}
  C -->|"yes"| N["no change"]
  C -->|"no"| A["apply change"]
  A --> D

2. Prefer state assertions over imperative repetition

mkdir -p -- "$config_dir"

if [[ ! -f $config_file ]]; then
  printf '%s\n' 'enabled=true' > "$config_file"
fi

The script describes what should exist rather than assuming it is always starting from an empty machine.

3. Compare before replacing content

tmp=$(mktemp) || exit 1
render_config > "$tmp"

if cmp -s -- "$tmp" "$target"; then
  printf 'config already current\n'
  rm -f -- "$tmp"
else
  mv -- "$tmp" "$target"
fi

Avoid rewriting unchanged files when timestamps, service reloads, deployment triggers, or audit logs depend on actual changes.

4. Blind append is a classic non-idempotent operation

# Fragile:
# printf '%s\n' 'export APP_ENV=prod' >> ~/.profile

# Safer:
line='export APP_ENV=prod'
grep -Fxq -- "$line" ~/.profile 2>/dev/null ||
  printf '%s\n' "$line" >> ~/.profile

5. Service state should be checked or delegated

if systemctl is-active --quiet myapp.service; then
  printf 'service already active\n'
else
  systemctl start myapp.service
fi

Whenever possible, use management tools whose commands are already convergent instead of reconstructing state logic in Bash.

6. Installation checks should use authoritative state

if command -v jq >/dev/null 2>&1; then
  printf 'jq already installed\n'
else
  printf 'jq missing\n' >&2
  exit 69
fi

Do not infer installed state from incidental files when a package manager or executable lookup provides a more authoritative check.

7. Idempotent deletion treats absence as success

rm -f -- "$cache_file"
rm -rf -- "$cache_dir"

The goal is “this managed path must be absent.” Re-running should succeed when it is already gone.

8. Separate check, plan, and apply when risk is high

if needs_update; then
  printf 'PLAN update service=%s\n' "$service"

  if [[ $dry_run != true ]]; then
    apply_update
  fi
else
  printf 'NOOP service=%s already current\n' "$service"
fi

A visible NOOP result is valuable: operators can distinguish “nothing needed” from “the script silently failed.”

9. Partial success must still converge on rerun

Suppose a deployment creates a directory, copies two files, then fails before the third. A robust rerun should inspect current state and continue toward the desired result rather than duplicate or destroy the successful steps.

10. Not every external API operation is idempotent

11. Hands-on lab: convergent local deployment

mkdir -p "$HOME/devops-academy/bash/chapter12/lesson01"
cd "$HOME/devops-academy/bash/chapter12/lesson01"

deploy() {
  local target=./app
  local desired='version=2'

  mkdir -p -- "$target"

  tmp=$(mktemp) || return 1
  printf '%s\n' "$desired" > "$tmp"

  if [[ -f $target/config && $(cat "$target/config") == "$desired" ]]; then
    printf 'NOOP config already current\n'
    rm -f -- "$tmp"
  else
    mv -- "$tmp" "$target/config"
    printf 'CHANGED config updated\n'
  fi

  chmod 0644 -- "$target/config"
}

deploy
deploy

12. Knowledge check

13. Summary

Idempotent shell automation checks current state and converges on desired state. Prefer declarative checks, content comparison, explicit NOOPs, repeat-safe deletion, and authoritative external-state queries. Treat remote side effects according to their own idempotency contract.

14. Further reading

• GNU Coreutils manuals — mkdir, cmp, install, rm.
• systemd documentation — service state operations.
• HTTP semantics documentation — idempotent methods.
• Infrastructure-as-code documentation on convergence and idempotency.