yq Session 03: Editing

The killer feature of yq: modifying YAML files in place. This session covers -i for in-place edits, merging documents, deleting keys, and adding new entries.

Pre-Session State

  • Can filter and select YAML data

  • Can check keys with has

  • Understand YAML mappings and sequences

Setup

cat > /tmp/yq-edit.yaml << 'EOF'
name: domus-test
version: "~"
asciidoc:
  attributes:
    domain: inside.domusdigitalis.dev
    ise-pan-ip: 10.50.1.20
    port-dns: 53
nav:
  - modules/ROOT/nav.adoc
EOF
cp /tmp/yq-edit.yaml /tmp/yq-edit-backup.yaml

Always back up before practicing in-place edits.

Lesson 1: Update Values

Concept: .key = "value" sets a value. Add -i to modify the file.

Exercise 1.1: Update without -i (preview)

yq '.version = "1.0"' /tmp/yq-edit.yaml

Output: Modified YAML to stdout. File unchanged.

Exercise 1.2: Update with -i (in-place)

yq -i '.version = "1.0"' /tmp/yq-edit.yaml
cat /tmp/yq-edit.yaml

Output: File is now modified. version: "1.0".

Exercise 1.3: Update nested value

yq -i '.asciidoc.attributes.port-dns = 5353' /tmp/yq-edit.yaml
yq '.asciidoc.attributes.port-dns' /tmp/yq-edit.yaml

Lesson 2: Add New Keys

Concept: Assigning to a non-existent key creates it.

Exercise 2.1: Add a new attribute

yq -i '.asciidoc.attributes.vault-ip = "10.50.1.60"' /tmp/yq-edit.yaml
yq '.asciidoc.attributes' /tmp/yq-edit.yaml

Exercise 2.2: Add to a sequence

yq -i '.nav += ["modules/tutorials/nav.adoc"]' /tmp/yq-edit.yaml
yq '.nav' /tmp/yq-edit.yaml

Output: nav now has two entries.

Exercise 2.3: Add a new top-level key

yq -i '.ext.extensions = ["@antora/lunr-extension"]' /tmp/yq-edit.yaml
yq '.ext' /tmp/yq-edit.yaml

Lesson 3: Delete Keys

Concept: del(.key) removes a key from the mapping.

Exercise 3.1: Delete an attribute

yq -i 'del(.asciidoc.attributes.port-dns)' /tmp/yq-edit.yaml
yq '.asciidoc.attributes' /tmp/yq-edit.yaml

port-dns is gone.

Exercise 3.2: Delete from a sequence by value

yq -i '.nav -= ["modules/tutorials/nav.adoc"]' /tmp/yq-edit.yaml
yq '.nav' /tmp/yq-edit.yaml

Lesson 4: Merge Documents

Concept: * merges two mappings. Load a second file with load().

Exercise 4.1: Merge from another file

cat > /tmp/yq-overlay.yaml << 'EOF'
asciidoc:
  attributes:
    new-attr: "overlay-value"
    domain: override.example.com
EOF
yq '. * load("/tmp/yq-overlay.yaml")' /tmp/yq-edit.yaml

Output: domain is overridden, new-attr is added. Existing keys preserved.

Exercise 4.2: Merge without overwriting (select merge)

yq 'select(fi == 0) * select(fi == 1)' /tmp/yq-edit.yaml /tmp/yq-overlay.yaml

fi is the file index. This merges file 0 with file 1.

Lesson 5: Conditional Updates

Concept: Combine select with assignment for targeted edits.

Exercise 5.1: Update if exists

cp /tmp/yq-edit-backup.yaml /tmp/yq-cond.yaml
yq -i '(.asciidoc.attributes | select(has("ise-pan-ip")))."ise-pan-ip" = "10.50.1.21"' /tmp/yq-cond.yaml
yq '.asciidoc.attributes.ise-pan-ip' /tmp/yq-cond.yaml

Only updates if the key already exists.

Summary: What You Learned

Concept Syntax Example

Set value

.key = val

.version = "1.0"

In-place

-i

yq -i '.key = val' file.yaml

Add to seq

+=

.nav += ["new.adoc"]

Delete key

del(.key)

del(.asciidoc.attributes.old)

Merge

*

. * load("overlay.yaml")

File index

fi

select(fi == 0)

Exercises to Complete

  1. [ ] Restore from backup, add 3 new attributes, verify

  2. [ ] Delete ise-pan-ip, add ise-01-ip with the same value (rename pattern)

  3. [ ] Merge two antora.yml overlays in sequence

  4. [ ] Add a comment to a key (hint: .key line_comment = "note")

Next Session

Session 04: Multi-Document - Multi-doc YAML, anchors, aliases.

Session Log

Timestamp Notes

Start

<Record when you started>

End

<Record when you finished>