yamlfmt

yamlfmt is an extensible command line tool or library to format yaml files.

Goals

• Create a command line yaml formatting tool that is easy to distribute (single binary)
• Make it simple to extend with new custom formatters
• Enable alternative use as a library, providing a foundation for users to create a tool that meets specific needs

Maintainers

This tool is not yet officially supported by Google. It is currently maintained solely by @braydonk, and unless something changes primarily in spare time.

Blog

I'm going to use these links to GitHub Discussions as a blog of sorts, until I can set up something more proper:

• yamlfmt's recent slow development #149
• Issues related to the yaml.v3 library #148

Installation

To download the yamlfmt command, you can download the desired binary from releases or install the module directly:

go install github.com/google/yamlfmt/cmd/yamlfmt@latest

This currently requires Go version 1.21 or greater.

NOTE: Recommended setup if this is your first time installing Go would be in this DigitalOcean blog post.

You can also download the binary you want from releases. The binary is self-sufficient with no dependencies, and can simply be put somewhere on your PATH and run with the command yamlfmt. Read more about verifying the authenticity of released artifacts here.

You can also install the command as a pre-commit hook. See the pre-commit hook docs for instructions.

Basic Usage

See Command Usage for in-depth information and available flags.

To run the tool with all default settings, run the command with a path argument:

yamlfmt x.yaml y.yaml <...>

You can specify as many paths as you want. You can also specify a directory which will be searched recursively for any files with the extension .yaml or .yml.

yamlfmt .

You can also use an alternate mode that will search paths with doublestar globs by supplying the -dstar flag.

yamlfmt -dstar **/*.{yaml,yml}

See the doublestar package for more information on this format.

Configuration File

The yamlfmt command can be configured through a yaml file called .yamlfmt. This file can live in your working directory, a path specified through a CLI flag, or in the standard global config path on your system (see docs for specifics). For in-depth configuration documentation see Config.

Verifying release artifacts

NOTE: Support for verifying with cosign is present from v0.14.0 onward.

In case you get the yamlfmt binary directly from a release, you may want to verify its authenticity. Checksums are applied to all released artifacts, and the resulting checksum file is signed using cosign.

Steps to verify (replace A.B.C in the commands listed below with the version you want):

1. Download the following files from the release:

   curl -sfLO https://github.com/google/yamlfmt/releases/download/vA.B.C/checksums.txt
   curl -sfLO https://github.com/google/yamlfmt/releases/download/vA.B.C/checksums.txt.pem
   curl -sfLO https://github.com/google/yamlfmt/releases/download/vA.B.C/checksums.txt.sig
   

2. Verify the signature:

    cosign verify-blob checksums.txt \
       --certificate checksums.txt.pem \
       --signature checksums.txt.sig \
       --certificate-identity-regexp 'https://github\.com/google/yamlfmt/\.github/workflows/.+' \
       --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

3. Download the compressed archive you want, and validate its checksum:

   curl -sfLO https://github.com/google/yamlfmt/releases/download/vA.B.C/yamlfmt_A.B.C_Linux_x86_64.tar.gz
   sha256sum --ignore-missing -c checksums.txt

4. If checksum validation goes through, uncompress the archive:

   tar -xzf yamlfmt_A.B.C_Linux_x86_64.tar.gz
   ./yamlfmt