zizmor/crates/yamlpatch

yamlpatch

Comment and format-preserving YAML patch operations.

yamlpatch builds on yamlpath to provide surgical modification capabilities while preserving comments, formatting, and structure.

Important

This is not a substitute for comprehensive YAML processing libraries. It's designed for targeted modifications that preserve the original document's formatting and comments.

Why?

When working with YAML configuration files, it's often necessary to make programmatic changes while preserving the human-readable aspects of the file: comments, formatting, indentation, and style choices.

Traditional YAML processing involves parsing to a document model, making changes, and re-serializing. This approach destroys the original formatting and comments, making the result less suitable for version control and human review.

yamlpatch solves this by providing targeted patch operations that:

• Preserve comments and their positioning
• Maintain original indentation and formatting
• Respect different YAML styles (block vs. flow, single vs. multi-line)
• Support precise fragment rewriting within string values
• Handle complex nested structures gracefully

Operations

yamlpatch supports the following patch operations:

• Replace: Replace a value at a specific path
• Add: Add new key-value pairs to mappings
• Remove: Remove keys or elements
• MergeInto: Merge values into existing mappings
• Append: Append items to block sequences
• ReplaceComment: Replace comments associated with features
• RewriteFragment: Rewrite portions of string values (useful for templating)

Each operation preserves the document's formatting and structure (as best-effort).

License

MIT License.