yamlfmt

package module
v0.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 10, 2025 License: Apache-2.0 Imports: 17 Imported by: 4

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

Yamlfmt can also be used in ci/cd pipelines which supports running containers. The following snippet shows an example job for GitLab CI:

yaml lint:
  image: ghcr.io/google/yamlfmt:latest
  before_script:
    - apk add git
  script:
    - yamlfmt .
    - git diff --exit-code

The Docker image can also be used to run yamlfmt without installing it on your system. Just mount the directory you want to format as a volume (/project is used by default):

docker run -v "$(pwd):/project" ghcr.io/google/yamlfmt:latest <yamlfmt args>

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

Documentation

Index

Constants

View Source 
const DefaultPatternFile = "yamlfmt.patterns"
View Source 
const MetadataIdentifier = "!yamlfmt!"

Variables

View Source 
var (
	ErrMalformedMetadata    = errors.New("metadata: malformed string")
	ErrUnrecognizedMetadata = errors.New("metadata: unrecognized type")
)

Functions

func ExcludeWithGitignore added in v0.11.0 

func ExcludeWithGitignore(gitignorePath string, paths []string) ([]string, error)

func IsMetadataType added in v0.9.0 

func IsMetadataType(mdValueStr string) bool

func ReadMetadata added in v0.9.0 

func ReadMetadata(content []byte, path string) (collections.Set[Metadata], collections.Errors)

Types

type BasicContentAnalyzer added in v0.9.0 

type BasicContentAnalyzer struct {
	RegexPatterns []*regexp.Regexp
}

func NewBasicContentAnalyzer added in v0.9.0 

func NewBasicContentAnalyzer(patterns []string) (BasicContentAnalyzer, error)

func (BasicContentAnalyzer) ExcludePathsByContent added in v0.9.0 

func (a BasicContentAnalyzer) ExcludePathsByContent(paths []string) ([]string, []string, error)

type ContentAnalyzer added in v0.9.0 

type ContentAnalyzer interface {
	ExcludePathsByContent(paths []string) ([]string, []string, error)
}

type DoublestarCollector added in v0.7.0 

type DoublestarCollector struct {
	Include []string
	Exclude []string
}

func (*DoublestarCollector) CollectPaths added in v0.7.0 

func (c *DoublestarCollector) CollectPaths() ([]string, error)

type Engine added in v0.8.0 

type Engine interface {
	FormatContent(content []byte) ([]byte, error)
	Format(paths []string) (fmt.Stringer, error)
	Lint(paths []string) (fmt.Stringer, error)
	DryRun(paths []string) (fmt.Stringer, error)
}

type Factory 

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

type Feature added in v0.4.0 

type Feature struct {
	Name         string
	BeforeAction FeatureFunc
	AfterAction  FeatureFunc
}

type FeatureApplyError added in v0.4.0 

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

func (*FeatureApplyError) Error added in v0.4.0 

func (e *FeatureApplyError) Error() string

func (*FeatureApplyError) Unwrap added in v0.4.0 

func (e *FeatureApplyError) Unwrap() error

type FeatureApplyMode added in v0.4.0 

type FeatureApplyMode string
var (
	FeatureApplyBefore FeatureApplyMode = "Before"
	FeatureApplyAfter  FeatureApplyMode = "After"
)

type FeatureFunc added in v0.4.0 

type FeatureFunc func(context.Context, []byte) (context.Context, []byte, error)

type FeatureList added in v0.4.0 

type FeatureList []Feature

func (FeatureList) ApplyFeatures added in v0.4.0 

func (fl FeatureList) ApplyFeatures(ctx context.Context, input []byte, mode FeatureApplyMode) (context.Context, []byte, error)

type FileDiff added in v0.8.0 

type FileDiff struct {
	Path string
	Diff *FormatDiff
}

func (*FileDiff) Apply added in v0.8.0 

func (fd *FileDiff) Apply() error

func (*FileDiff) StrOutput added in v0.8.0 

func (fd *FileDiff) StrOutput() string

func (*FileDiff) StrOutputQuiet added in v0.8.0 

func (fd *FileDiff) StrOutputQuiet() string

type FileDiffs added in v0.8.0 

type FileDiffs map[string]*FileDiff

func (FileDiffs) Add added in v0.8.0 

func (fds FileDiffs) Add(diff *FileDiff) error

func (FileDiffs) ApplyAll added in v0.8.0 

func (fds FileDiffs) ApplyAll() error

func (FileDiffs) ChangedCount added in v0.8.0 

func (fds FileDiffs) ChangedCount() int

func (FileDiffs) StrOutput added in v0.8.0 

func (fds FileDiffs) StrOutput() string

func (FileDiffs) StrOutputQuiet added in v0.8.0 

func (fds FileDiffs) StrOutputQuiet() string

type FilepathCollector added in v0.7.0 

type FilepathCollector struct {
	Include    []string
	Exclude    []string
	Extensions []string
}

func (*FilepathCollector) CollectPaths added in v0.7.0 

func (c *FilepathCollector) CollectPaths() ([]string, error)

type FormatDiff added in v0.8.0 

type FormatDiff struct {
	Original  string
	Formatted string
	LineSep   string
}

func (*FormatDiff) Changed added in v0.8.0 

func (d *FormatDiff) Changed() bool

func (*FormatDiff) MultilineDiff added in v0.8.0 

func (d *FormatDiff) MultilineDiff() (string, int)

type Formatter 

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

type LineBreakStyle added in v0.5.0 

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

func (LineBreakStyle) Separator added in v0.5.0 

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

type MatchType added in v0.15.0 

type MatchType string
const (
	MatchTypeStandard   MatchType = "standard"
	MatchTypeDoublestar MatchType = "doublestar"
	MatchTypeGitignore  MatchType = "gitignore"
)

type Metadata added in v0.9.0 

type Metadata struct {
	Type    MetadataType
	LineNum int
}

type MetadataError added in v0.9.0 

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

func (*MetadataError) Error added in v0.9.0 

func (e *MetadataError) Error() string

func (*MetadataError) Unwrap added in v0.9.0 

func (e *MetadataError) Unwrap() error

type MetadataType added in v0.9.0 

type MetadataType string
const (
	MetadataIgnore MetadataType = "ignore"
)

type Operation added in v0.12.0 

type Operation int
const (
	OperationFormat Operation = iota
	OperationLint
	OperationDry
	OperationStdin
	OperationPrintConfig
)

type PathCollector added in v0.7.0 

type PathCollector interface {
	CollectPaths() ([]string, error)
}

type PatternFileCollector added in v0.15.0 

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

PatternFileCollector determines which files to format and which to ignore based on a pattern file in gitignore(5) syntax.

func NewPatternFileCollector added in v0.15.0 

func NewPatternFileCollector(files ...string) (*PatternFileCollector, error)

NewPatternFileCollector initializes a new PatternFile using the provided file(s). If multiple files are provided, their content is concatenated in order. All patterns are relative to the current working directory.

func NewPatternFileCollectorFS added in v0.15.0 

func NewPatternFileCollectorFS(r io.Reader, fs fs.FS) *PatternFileCollector

NewPatternFileCollectorFS reads a pattern file from r and uses fs for file lookups. It is used by NewPatternFile and primarily public because it is useful for testing.

func (*PatternFileCollector) CollectPaths added in v0.15.0 

func (c *PatternFileCollector) CollectPaths() ([]string, error)

CollectPaths implements the PathCollector interface.

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 added in v0.5.0 

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

func (UnsupportedLineBreakError) Error added in v0.5.0 

func (e UnsupportedLineBreakError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
cmd
yamlfmt
formatters
basic
basic/anchors
internal
assert
collections
features
gitlab
Package gitlab generates GitLab Code Quality reports.
 Package gitlab generates GitLab Code Quality reports.
hotfix
logger
multilinediff
tempfile

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.