How to use the command `yq` (with examples)

The yq command is a lightweight and portable command-line YAML processor. It allows users to manipulate YAML files directly from the command line. With its simple syntax and ease of use, yq is a powerful tool for working with YAML data.

Use case 1: Output a YAML file in pretty-print format (v4+)

Code:

yq eval path/to/file.yaml

Motivation:

The yq eval command can be used to pretty-print a YAML file in a human-readable format. This is especially useful when working with large and complex YAML files, as it makes it easier to understand the structure and contents of the file.

Explanation:

• yq eval: The eval command allows for evaluating an expression on input YAML data.
• path/to/file.yaml: This is the path to the input YAML file.

Example output:

key1: value1
key2:
  - item1
  - item2

Use case 2: Output a YAML file in pretty-print format (v3)

Code:

yq read path/to/file.yaml --colors

Motivation:

The yq read command can be used to pretty-print a YAML file in a human-readable format for versions of YAML prior to version 4. This can be useful when working with legacy YAML files that do not adhere to the latest version of the specification.

Explanation:

• yq read: The read command is used to read a YAML file.
• path/to/file.yaml: This is the path to the input YAML file.
• --colors: This flag adds color coding to the output, making it easier to visually distinguish different elements in the YAML file.

Example output:

key1: value1
key2:
  - item1
  - item2

Use case 3: Output the first element in a YAML file that contains only an array (v4+)

Code:

yq eval '.[0]' path/to/file.yaml

Motivation:

The yq eval command with an expression can be used to extract specific elements from a YAML file. In this case, we can use the expression .[] to extract the first element from a YAML file that contains only an array. This can be useful when working with YAML files that contain large arrays and we only need to retrieve specific elements.

Explanation:

• yq eval: The eval command allows for evaluating an expression on input YAML data.
• '.[0]': This expression selects the first element of an array in the YAML file.
• path/to/file.yaml: This is the path to the input YAML file.

Example output:

item1

Use case 4: Output the first element in a YAML file that contains only an array (v3)

Code:

yq read path/to/file.yaml '[0]'

Motivation:

Similar to the previous use case, the yq read command with an expression can be used to extract specific elements from a YAML file. This command is specifically for YAML files that adhere to versions prior to version 4.

Explanation:

• yq read: The read command is used to read a YAML file.
• path/to/file.yaml: This is the path to the input YAML file.
• '[0]': This expression selects the first element of an array in the YAML file.

Example output:

item1

Use case 5: Set (or overwrite) a key to a value in a file (v4+)

Code:

yq eval '.key = "value"' --inplace path/to/file.yaml

Motivation:

The yq eval command can be used to modify the contents of a YAML file by setting or overwriting specific key-value pairs. This is useful when we need to update certain values in a YAML file without manually editing the file.

Explanation:

• yq eval: The eval command allows for evaluating an expression on input YAML data.
• '.key = "value"': This expression sets the value of the key key to "value".
• --inplace: This flag modifies the original file in-place instead of creating a new file.
• path/to/file.yaml: This is the path to the input YAML file.

Example output:

After running the command, the value of the key key in the YAML file will be updated to "value".

Use case 6: Set (or overwrite) a key to a value in a file (v3)

Code:

yq write --inplace path/to/file.yaml 'key' 'value'

Motivation:

Similar to the previous use case, this command allows for setting or overwriting a key-value pair in a YAML file. This command is specifically for YAML files that adhere to versions prior to version 4.

Explanation:

• yq write: The write command is used to modify a YAML file.
• --inplace: This flag modifies the original file in-place instead of creating a new file.
• path/to/file.yaml: This is the path to the input YAML file.
• 'key' 'value': This specifies the key-value pair to set or overwrite in the YAML file.

Example output:

After running the command, the value of the key key in the YAML file will be updated to 'value'.

Use case 7: Merge two files and print to stdout (v4+)

Code:

yq eval-all 'select(filename == "path/to/file1.yaml") * select(filename == "path/to/file2.yaml")' path/to/file1.yaml path/to/file2.yaml

Motivation:

The yq eval-all command can be used to merge the contents of two YAML files and print the result to stdout. This is useful when we need to combine the data from multiple YAML files into a single file or when we want to compare the differences between the two files.

Explanation:

• yq eval-all: The eval-all command evaluates an expression on multiple input YAML files.
• 'select(filename == "path/to/file1.yaml") * select(filename == "path/to/file2.yaml")': This expression selects the contents of both files and merges them together.
• path/to/file1.yaml path/to/file2.yaml: These are the paths to the input YAML files.

Example output:

The contents of path/to/file1.yaml and path/to/file2.yaml will be merged together and printed to stdout.

Use case 8: Merge two files and print to stdout (v3)

Code:

yq merge path/to/file1.yaml path/to/file2.yaml --colors

Motivation:

Similar to the previous use case, this command allows for merging two YAML files together and printing the result to stdout. This command is specific to YAML files that adhere to versions prior to version 4.

Explanation:

• yq merge: The merge command is used to merge the contents of two YAML files.
• path/to/file1.yaml path/to/file2.yaml: These are the paths to the input YAML files.
• --colors: This flag adds color coding to the output, making it easier to visually distinguish different elements in the merged file.

Example output:

The contents of path/to/file1.yaml and path/to/file2.yaml will be merged together and printed to stdout, with color coding added for better visualization.

Conclusion:

The yq command is a versatile tool for working with YAML files on the command line. It allows users to perform a wide range of operations, including formatting, extracting elements, modifying values, and merging files. By understanding the various use cases and examples provided, users can leverage the power of yq to efficiently manipulate YAML data.