yamlfmt

The yamlfmt command operates in one of three primary modes:

1. Format (Default): Collects all matching paths and rewrites each file with the formatted results.
2. Dry Run (-dry): Collects matching paths and runs them through formatting, but instead of writing changes, it prints the formatting diffs to stdout. This mode is affected by the -quiet flag.
3. Lint (-lint): Collects matching paths and runs them through formatting. If any files have formatting differences, it outputs the diffs to stdout and exits with code 1. This mode is also affected by the -quiet flag.

Note on Quiet Mode: When using -quiet (or -q) in Dry Run or Lint modes, only the paths of the files with diffs are printed, rather than the full diffs.

The yaml package supports most of YAML 1.2 but maintains certain YAML 1.1 behaviors for backwards compatibility:

• Booleans: YAML 1.1 bools (_yes/no, _on/off_) are supported when decoding into a typed bool value. Otherwise, they are treated as strings. YAML 1.2 only uses true/false.
• Octals: Encodes and decodes as _0777_ (YAML 1.1 style) to maintain compatibility with most parsers, though the YAML 1.2 _0o777_ format is also supported.
• Unsupported: Base-60 floats (from YAML 1.1) are not supported. Multi-document unmarshalling is not yet implemented.

If you prefer to manage the yamlfmt installation yourself rather than having pre-commit build it with Go, you can override the language setting to system. This requires the yamlfmt binary to be present in your PATH.

- repo: https://github.com/google/yamlfmt
  rev: v0.19.0
  hooks:
    - id: yamlfmt
      language: system

By default, the hook runs on all staged .yaml files. To target other filetypes, override the types and files configuration in your .pre-commit-config.yaml.

- repo: https://github.com/google/yamlfmt
  rev: v0.19.0
  hooks:
    - id: yamlfmt
      types: [file]
      files: <filepath regex>

The gitignore mode uses .gitignore syntax to include or exclude files.

Key behaviors:

• yamlfmt formats files that match the patterns listed in the pattern file (unless the pattern is negated with !).
• If no pattern file is specified, yamlfmt looks for a file named yamlfmt.patterns in the working directory.
• Positional arguments on the command line and files listed in the include config option are treated as pattern files.
• The exclude option is ignored in this mode.

Example pattern file content:

# Include these extensions
*.yaml
*.yml

# Exclude the testdata directory
!testdata/

To use wildcard patterns (globbing) to specify files, enable doublestar mode. This is useful when you want to match patterns like **/*.yaml.

Enable it by setting match_type: doublestar in your configuration file or using the -match_type doublestar flag.

To run the command integration tests, which execute the yamlfmt binary against various command combinations in temporary directories, use the make command. This process builds the binary and executes the test suite.

If you need to update the golden files (the expected outputs and directory states) used for comparison, you must ensure the test environment is configured to handle updates.

make integrationtest

To configure a formatter, specify its type within the formatter block. Each formatter type (e.g., basic, kyaml) has its own unique set of configuration options. Providing options intended for one formatter type to another will cause yamlfmt to fail.

# Using the basic formatter with options
formatter:
  type: basic
  indent: 4
  include_document_start: true

# Switching to the kyaml formatter
formatter:
  type: kyaml

The gitlab output format generates a JSON report compatible with GitLab Code Quality. This allows formatting issues to appear directly in GitLab Merge Request widgets.

To produce a more compact JSON output, combine this format with the -quiet flag.

yamlfmt:
  script:
    - yamlfmt -dry -output_format gitlab . >yamlfmt-report
  artifacts:
    when: always
    reports:
      codequality: yamlfmt-report

To format YAML files, run the yamlfmt command followed by the paths to the files or directories you wish to process.

• Files: Specify individual file paths.
• Directories: Specify a directory to search recursively for .yaml or .yml files.
• Doublestar Globs: Use the -dstar flag to enable support for doublestar globs (e.g., **/*.yaml).

For detailed information on available flags, see the Command Usage documentation.