Comment Operators
Use these comment operators to set or retrieve comments. Note that line comments on maps/arrays are actually set on the key node as opposed to the value (map/array). See below for examples.
Like the
= and |= assign operators, the same syntax applies when updating comments:This will set the LHS nodes' comments equal to the expression on the RHS. The RHS is run against the matching nodes in the pipeline
This is similar to the plain form, but it evaluates the RHS with each matching LHS node as context. This is useful if you want to set the comments as a relative expression of the node, for instance its value or path.
Set the comment on the key node for more reliability (see below).
Given a sample.yml file of:
a: cat
then
yq '.a line_comment="single"' sample.yml
will output
a: cat # single
For maps and arrays, you need to set the line comment on the key node. This will also work for scalars.
Given a sample.yml file of:
a:
b: things
then
yq '(.a | key) line_comment="single"' sample.yml
will output
a: # single
b: things
Given a sample.yml file of:
a: cat
b: dog
then
yq '.. line_comment |= .' sample.yml
will output
a: cat # cat
b: dog # dog
The underlying yaml parser can assign comments in a document to surprising nodes. Use an expression like this to find where you comment is. 'p' indicates the path, 'isKey' is if the node is a map key (as opposed to a map value). From this, you can see the 'hello-world-comment' is actually on the 'hello' key
Given a sample.yml file of:
hello: # hello-world-comment
message: world
then
yq '[... | {"p": path | join("."), "isKey": is_key, "hc": headComment, "lc": lineComment, "fc": footComment}]' sample.yml
will output
- p: ""
isKey: false
hc: ""
lc: ""
fc: ""
- p: hello
isKey: true
hc: ""
lc: hello-world-comment
fc: ""
- p: hello
isKey: false
hc: ""
lc: ""
fc: ""
- p: hello.message
isKey: true
hc: ""
lc: ""
fc: ""
- p: hello.message
isKey: false
hc: ""
lc: ""
fc: ""
From the previous example, we know that the comment is on the 'hello' key as a lineComment
Given a sample.yml file of:
hello: # hello-world-comment
message: world
then
yq '.hello | key | line_comment' sample.yml
will output
hello-world-comment
The underlying yaml parser can assign comments in a document to surprising nodes. Use an expression like this to find where you comment is. 'p' indicates the path, 'isKey' is if the node is a map key (as opposed to a map value). From this, you can see the 'under-name-comment' is actually on the first child
Given a sample.yml file of:
name:
# under-name-comment
- first-array-child
then
yq '[... | {"p": path | join("."), "isKey": is_key, "hc": headComment, "lc": lineComment, "fc": footComment}]' sample.yml
will output
- p: ""
isKey: false
hc: ""
lc: ""
fc: ""
- p: name
isKey: true
hc: ""
lc: ""
fc: ""
- p: name
isKey: false
hc: ""
lc: ""
fc: ""
- p: name.0
isKey: false
hc: under-name-comment
lc: ""
fc: ""
From the previous example, we know that the comment is on the first child as a headComment
Given a sample.yml file of:
name:
# under-name-comment
- first-array-child
then
yq '.name[0] | headComment' sample.yml
will output
under-name-comment
Given a sample.yml file of:
a: cat
then
yq '. head_comment="single"' sample.yml
will output
# single
a: cat
Given a sample.yml file of:
f: foo
a:
b: cat
then
yq '(.a | key) head_comment="single"' sample.yml
will output
f: foo
# single
a:
b: cat
Given a sample.yml file of:
a: cat
then
yq '. foot_comment=.a' sample.yml
will output
a: cat
# cat
Given a sample.yml file of:
a: cat # comment
b: dog # leave this
then
yq '.a line_comment=""' sample.yml
will output
a: cat
b: dog # leave this
Note the use of
... to ensure key nodes are included.Given a sample.yml file of:
# hi
a: cat # comment
# great
b: # key comment
then
yq '... comments=""' sample.yml
will output
a: cat
b:
Given a sample.yml file of:
# welcome!
a: cat # meow
# have a great day
then
yq '.a | line_comment' sample.yml
will output
meow
Given a sample.yml file of:
# welcome!
a: cat # meow
# have a great day
then
yq '. | head_comment' sample.yml
will output
welcome!
Given a sample.yml file of:
# welcome!
---
# bob
a: cat # meow
# have a great day
then
yq 'head_comment' sample.yml
will output
welcome!
bob
Given a sample.yml file of:
# welcome!
a: cat # meow
# have a great day
# no really
then
yq '. | foot_comment' sample.yml
will output
have a great day
no really
Last modified 6mo ago