yamlfmt

README

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 currenlty maintained solely by @braydonk.

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

Usage

By default, the tool will recursively find all files that match the glob path **/*.{yaml,yml} extension and attempt to format them with the basic formatter. To run the tool with all default settings, simply run the command with no arguments:

yamlfmt

You can also run the command with paths to each individual file, or with glob paths:

yamlfmt x.yaml y.yaml config/**/*.yaml

(NOTE: Glob paths are implemented using the doublestar package, which is far more flexible than Go's glob implementation. See the doublestar docs for more details.)

Configuration

The tool can be configured with a .yamlfmt configuration file in the working directory. The configuration is specified in yaml.

Include/Exclude

If you would like to have a consistent configuration for include and exclude paths, you can also use a configuration file. The tool will attempt to read a configuration file named .yamlfmt in the directory the tool is run on. In it, you can configure paths to include and exclude, for example:

include:
  - config/**/*.{yaml,yml}
exclude:
  - excluded/**/*.yaml

Line Ending

The default line ending is lf (Unix style, Mac/Linux). The line ending can be changed to crlf (Windows style) with the line_ending setting:

line_ending: crlf

This setting will be sent to any formatter as a config field called line_ending. If a line_ending is specified in the formatter, this will overwrite it. New formatters are free to ignore this setting if they don't need it, but any formatter provided by this repo will handle it accordingly.

Formatter

In your .yamlfmt file you can also specify configuration for the formatter if that formatter supports it. To change the indentation level of the basic formatter for example:

formatter:
  type: basic
  indent: 4

If the type is not specified, the default formatter will be used. In the tool included in this repo, the default is the basic formatter.

Flags

The CLI supports the following flags/arguments:

• Format (default, no flags)
  • Format and write the matched files
• Dry run (-dry flag)
  • Format the matched files and output the diff to stdout
• Lint (-lint flag)
  • Format the matched files and output the diff to stdout, exits with status 1 if there are any differences
• Stdin (just - or /dev/stdin argument, or -in flag)
  • Format the yaml data from stdin and output the result to stdout
• Custom config path (-conf flag)
  • If you would like to use a config not stored at .yamlfmt in the working directory, you can pass a relative or absolute path to a separate configuration file

(NOTE: If providing paths as command line arguments, the flags must be specified before any paths)

Documentation

Index

• type Factory
• type Feature
• type FeatureApplyError
  • func (e *FeatureApplyError) Error() string
  • func (e *FeatureApplyError) Unwrap() error
• type FeatureApplyMode
• type FeatureFunc
• type FeatureList
  • func (fl FeatureList) ApplyFeatures(input []byte, mode FeatureApplyMode) ([]byte, error)
• type Formatter
• type LineBreakStyle
  • func (s LineBreakStyle) Separator() (string, error)
• type Registry
  • func NewFormatterRegistry(defaultFactory Factory) *Registry
  • func (r *Registry) Add(f Factory)
  • func (r *Registry) GetDefaultFactory() (Factory, error)
  • func (r *Registry) GetFactory(fType string) (Factory, error)
• type UnsupportedLineBreakError
  • func (e UnsupportedLineBreakError) Error() string

Types

type Factory

type Factory interface {
	Type() string
	NewFormatter(config map[string]interface{}) (Formatter, error)
}

type Feature

type Feature struct {
	Name         string
	BeforeAction FeatureFunc
	AfterAction  FeatureFunc
}

type FeatureApplyError

type FeatureApplyError struct {
	// contains filtered or unexported fields
}

func (*FeatureApplyError) Error

func (e *FeatureApplyError) Error() string

func (*FeatureApplyError) Unwrap

func (e *FeatureApplyError) Unwrap() error

type FeatureApplyMode

type FeatureApplyMode string

var (
	FeatureApplyBefore FeatureApplyMode = "before"
	FeatureApplyAfter  FeatureApplyMode = "after"
)

type FeatureFunc

type FeatureFunc func([]byte) ([]byte, error)

type FeatureList

type FeatureList []Feature

func (FeatureList) ApplyFeatures

func (fl FeatureList) ApplyFeatures(input []byte, mode FeatureApplyMode) ([]byte, error)

type Formatter

type Formatter interface {
	Type() string
	Format(yamlContent []byte) ([]byte, error)
}

type LineBreakStyle

type LineBreakStyle string

const (
	LineBreakStyleLF   LineBreakStyle = "lf"
	LineBreakStyleCRLF LineBreakStyle = "crlf"
)

func (LineBreakStyle) Separator

func (s LineBreakStyle) Separator() (string, error)

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

func NewFormatterRegistry

func NewFormatterRegistry(defaultFactory Factory) *Registry

func (*Registry) Add

func (r *Registry) Add(f Factory)

func (*Registry) GetDefaultFactory

func (r *Registry) GetDefaultFactory() (Factory, error)

func (*Registry) GetFactory

func (r *Registry) GetFactory(fType string) (Factory, error)

type UnsupportedLineBreakError

type UnsupportedLineBreakError struct {
	// contains filtered or unexported fields
}

func (UnsupportedLineBreakError) Error

func (e UnsupportedLineBreakError) Error() string