docs: add file append and overwrite examples

[JasonColapietro]

Summary

• add a minimal file append example using explicit overwrite: false
• show both /etc/sudoers and the preferred /etc/sudoers.d/ drop-in form
• bound the passwordless sudo example to one exact command and warn against root-equivalent rules
• add a distinct contents example using overwrite: true

Testing

• ./test (passes; its docs loop reports that it is skipped on macOS when GNU csplit and head are unavailable)
• both changed snippets pass the built Butane binary with --check --strict
• git diff --check

Closes #499.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 77a9b2c2-e3e5-4a1e-b94c-0061e5c60c0d

📥 Commits

Reviewing files that changed from the base of the PR and between 4080fc6 and 745c987.

📒 Files selected for processing (1)

• docs/examples.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/examples.md

---

📝 Walkthrough

Walkthrough

Added file-storage examples that show how append preserves existing contents and how overwrite: true replaces an existing filesystem node.

Changes

File storage documentation

Layer / File(s)	Summary
Append and overwrite examples docs/examples.md	Added examples for appending sudoers content with overwrite: false, creating a sudoers drop-in with mode 0440, and replacing an existing filesystem node with inline file contents using overwrite: true.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Mergeability Score: ⚪ Minimal · up to 745c9

This documentation-only change adds examples for file append and overwrite behavior; no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The documentation adds an append example for /etc/sudoers with overwrite: false, satisfying issue #499.
Out of Scope Changes check	✅ Passed	The changes are limited to relevant documentation examples for append and overwrite behavior.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the documentation examples added for file append and overwrite behavior.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/examples.md`:
- Around line 152-166: Update the documentation example using the append
configuration to target /etc/sudoers as requested by Issue `#499`, or add a
separate /etc/sudoers example while retaining the existing /etc/sudoers.d/core
drop-in example if intentional. Keep the append behavior and overwrite: false
defaults unchanged.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f2dc77e9-b738-4f47-b608-46fb86850c9e

📥 Commits

Reviewing files that changed from the base of the PR and between cb34e12 and abb49b2.

📒 Files selected for processing (1)

• docs/examples.md

[JasonColapietro]

Good catch — the drop-in example didn't actually answer #499, which asked for an example appending to /etc/sudoers.

Pushed 4080fc6: the primary append example now targets /etc/sudoers exactly as the issue requested, and the /etc/sudoers.d/ drop-in follows as a short note explaining why it's usually preferable. Both blocks pass butane --check --strict locally.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/examples.md`:
- Around line 162-164: Restrict the Podman sudoers examples so they do not
present unrestricted passwordless root access: update the rule at
docs/examples.md lines 162-164 and the corresponding drop-in example at lines
178-180 with a bounded command and explicit arguments, or add a clear warning
that each rule grants root-equivalent access.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0daa423c-9fd1-4f94-b42e-fd45fa2d63c1

📥 Commits

Reviewing files that changed from the base of the PR and between 69b8b4f and 4080fc6.

📒 Files selected for processing (1)

• docs/examples.md

[yasminvalim]

Hey @JasonColapietro

Thanks for the PR! We’re archiving this repository as Butane is being merged into Ignition, so new changes should now go to Ignition:
https://github.com/coreos/ignition/pulls

We already created a new issue for this in ignition's repo: coreos/ignition#2270

You’re very welcome to reopen this work there and I will be glad to review. Thank you for contributing!

[JasonColapietro]

Thanks @yasminvalim — moved it over to coreos/ignition#2302, which ports these examples to butane/docs/examples.md and closes coreos/ignition#2270. Each block was re-validated with a butane binary built from the Ignition tree.

Closing this one.