Format files¶

This guide shows the different ways to feed YAML content to yamkix and control where the formatted output goes.

Check the available options with yamkix --help (or see the CLI options reference).

Format a single yaml file and control where to output the outcome¶

Use the -i/--input option to identify the source file
If you don't specify any output option with -o/--output or -s/--stdout then the result will overwrite the source file
```
yamkix --input path/to/yolo.yml
# the formatted result will overwrite the content at path/to/yolo.yml
```

You can specify the target file with -o/--output

yamkix --input path/to/yolo.yml --output path/to/nice.yml
# the formatted result will write the result at path/to/nice.yml
# if nice.yml exists, it will be overwritten

You can output the result to STDOUT using either --output STDOUT or -s/--stdout

yamkix --input path/to/yolo.yml --stdout
# output is written to STDOUT
---
toto: foo
titi:
  - bar
  - quix
tutu:
  yolo: baz

If you use -s/--stdout and -i/--input, specifying an output file with -o/--output will not be taken into account

yamkix --input path/to/yolo.yml -output path/to/nice.yml --stdout
# output is written to STDOUT
---
toto: foo
titi:
  - bar
  - quix
tutu:
  yolo: baz

Read from STDIN¶

You can format the input provide through stdin
stdin input can be specified explicitly, using --input STDIN
```
cat file.yml | yamkix --input STDIN
```
stdin input is implicit if you don't specify any input through -i/--input or any CLI argument:
```
cat file.yml | yamkix -q
```
if stdin is used for input and nothing is specified for output, then stdout will be used for output.

Format multiple files¶

If you need to format multiple files in a single call to Yamkix, don't use -i/--input, just pass the list of files as arguments to the yamkix cli
```
yamkix --silent path/to/file1.yml path/to/file2.yml
```

Note

It is not possible to output to stdout when formatting multiple files (feel free to raise an issue if you are interested in this feature).

Print a processing summary¶

Use --summary to print processing statistics after all files have been processed
The summary includes:
Total number of files processed
Number of files that encountered parse errors
Number of files with unchanged content (already properly formatted)

Total processing time

yamkix --summary path/to/file1.yml path/to/file2.yml
# Output:
# [yamkix] Summary: 2 file(s) processed, 0 error(s), 1 unchanged, 0.042s

When combined with --silent (which suppresses per-file config output), only the summary is printed to stderr:

yamkix --silent --summary path/to/file1.yml path/to/file2.yml
# Produces minimal output:
# [yamkix] Summary: 2 file(s) processed, 0 error(s), 1 unchanged, 0.042s

List the modified files¶

Use --list-modified to print one stderr line per output file created or whose content changed, after processing
For in-place formatting, the reported path is the input file. With --output, it is the destination, even if the source was already formatted. --stdout and special files such as /dev/null are not files whose content changed and produce no modified-file line
Changes are detected on raw bytes, so a file whose only change is its line endings (for example CRLF converted to LF) is listed, and not counted as unchanged by --summary
Unchanged destinations and files that failed to parse are not listed; no modified-file lines appear when nothing changed. A destination that cannot be read is listed, since it cannot be compared
If a later file fails to open, files modified earlier in the run are still listed before the command exits with an error. A file left partially written by a failure is listed too
Filenames containing control characters, or starting with a double quote, are printed between double quotes with backslash escapes (for example, a newline appears as "a\nb.yml"), to keep one unambiguous report per line
```
yamkix --silent --list-modified path/to/file1.yml path/to/file2.yml
# Output (file1.yml was already formatted):
# [yamkix] Modified: path/to/file2.yml
```
It can be combined with --summary: the modified files are listed before the summary line