Skip to content

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
    

Note

Output files are never left half-written: yamkix writes the result to a temporary file in the same directory, then moves it over the destination. If formatting or writing fails (for example, the disk is full), the destination keeps its previous content. The destination directory must therefore be writable. Symlinks are followed and permission bits are kept, but the replaced file belongs to the user running yamkix and no longer shares hard links.

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).

  • 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 whose write failed keeps its previous content and is not listed
  • 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