v0.14.0

Shoutouts To The Community Release

I have been in not the best health the last while, which is why this release took so long to cut. On the bright side, this release features more contributions from the community than from myself. Thank you to everyone who contributed!

Features

strip_directives

yaml.v3 does not support directives. The best thing to do would be to add some amount of support for directives, which I will do in the future just taking it as far as the parser not failing upon finding a directive. In the short term, I added a hotfix style feature that will strip the directives before formatting and put them back in. The feature is fraught with edge cases and only works reliably with directives at the top of the file. See the explanations I added in the docs.

gitignore_excludes searches up the directory structure for the nearest .gitignore

Arguably a fix, the gitignore_excludes feature will now look up the directory structure for the nearest .gitignore which unlocks monorepo usage patterns for yamlfmt.

JSON schema

The community has added a JSON Schema! I'm calling it out in release notes, but this is not tied to yamlfmt releases in any way. If you have any fixes or improvements to make, they will not need to be tied to git tags being cut.

I am not super familiar with JSON Schema; I will try my best not to break it and keep it up to date but I'm not gonna be great at addressing potential deeper issues with it.

Validating releases with cosign

The release artifacts now generate other artifacts that allow you to verify releases using the cosign tool.

Fixes

The line_ending setting in the formatter config is respected again

This was a regression in v0.13.0 where I did some refactors to config discovery. I uncovered an edge case in my original code to handle the line_ending setting in the formatter block (vs the global version). This has been fixed in this release.

eof_newline no longer panics on an empty file

If the file was empty, the eof_newline feature would panic. Never thought of that! This has been fixed.

Contributors

@thiagowfx added the JSON Schema
@Shion1305 fixed the eof_newline panic
@dhth added cosign support to releases
@nikaro added .gitignore discovery

I think this is the most contributors I've had in a release! Thank you everyone!

Changelog (generated)

• feat: introduce a json schema file for yamlfmt by @thiagowfx in #193
• 🐛 panic against empty file with eof_newline feature, resolves: #196 by @Shion1305 in #197
• fix: look for gitignore file until the git root by @nikaro in #200
• fix(json schema): remove additionalProperties any by @thiagowfx in #202
• Add JSON schema validity test by @braydonk in #203
• ci: sign checksum file with cosign by @dhth in #207
• Clarify that cosign support will only be present starting from v0.14.0 by @braydonk in #212
• command: correctly propogate line_ending setting by @braydonk in #216
• Add feature strip_directives by @braydonk in #217

Full Changelog: v0.13.0...v0.14.0

v0.13.0

The Airplane ✈️ Release

This release doesn't have anything to do with airplanes, but I did the last few PRs and cut the release while I was on a plane so that's what came to mind. 😄

Features

Print Config

With the new -print_conf flag, you can have yamlfmt print out all configuration values it is using (whether they are default or overridden by a config file). This in combination with -debug config should make figuring out yamlfmt config problems much simpler going forward!

Trim Trailing Whitespace

Using the formatter option trim_trailing_whitespace, you can now tell yamlfmt to trim any trailing whitespace from lines. This is helpful in general, but it is specifically useful if you are affected by #86. With trailing whitespace being trimmed, this buggy output shouldn't get tripped. Not a perfect solution, but hopefully should help.

EOF Newline

Using the formatter option eof_newline, yamlfmt will forcibly add a newline to the end of the file if it's not there already. This is for particular scenarios when retain_line_breaks is not turned on, but the newline at the end of files is still required.

Contributors

• @kachick contributed the -print_conf feature and was very receptive to feedback on their PR. They also contributed a fix to CI, and automatic versioning in the yamlfmt binary to avoid future bugs like what happened with v0.12.1. Thank you!
• @corneliusroemer contributed a documentation typo fix. Thank you!

v0.12.1

Fix stdin output

I made a mistake in the last release that caused the stdin operation to output a byte array instead of a properly casted string. I will add integration tests to save this from happening in the future.

Known Issue: I was in a rush to get this out when I saw it and forgot to manually update the version string, so yamlfmt -version will print v0.12.0 for this version.

v0.12.0 Release notes below.

---

Output Format Release

I have unfortunately been dealing with a long-running health problem that has made it difficult to do much work on this or any projects for the past couple of months. I did manage to get together some small features and fixes worth noting.

Features

Output Format

You can now choose different output formats for lint/dry run. The first alternate output format added is line, which makes it so instead of the full detailed output, yamlfmt outputs single lines for each file with formatting differences. This should allow for easier integration into tools like reviewdog. I have never used that tool, but if anyone is able to get an integration working, feel free to open a Discussion thread about it and let me know!

More config file name options

Last release, I added configuration file naming options to have the yaml extension, i.e. yamlfmt.yaml and yamlfmt.yml. The way I did that made it so you couldn't have config files with extension also be hidden. That is resolved now, so you can have .yamlfmt.yaml etc.

Bug Fixes

Don't write files if there is no diff

Previously, yamlfmt would always write all files set for formatting even when there would be no change. This meant the edited date of the file was always being updated even though nothing was meant to change. That should not happen anymore.

Fix -global_conf not working as documented

The -global_conf flag was not working as documented in the last release. If there was a local config, -global_conf would end up being ignored and the local config would be used first. This was not the intended functionality and it has been fixed.

Contributors

Thanks @kiliantyler for the catching the global configuration bug and opening a fix for it!

1k stars!

Thank you very much for over 1000 stars on GitHub! I appreciate the support, and I hope the tool continues to be useful to the community!

v0.12.0

Output Format Release

I have unfortunately been dealing with a long-running health problem that has made it difficult to do much work on this or any projects for the past couple of months. I did manage to get together some small features and fixes worth noting.

Features

Output Format

You can now choose different output formats for lint/dry run. The first alternate output format added is line, which makes it so instead of the full detailed output, yamlfmt outputs single lines for each file with formatting differences. This should allow for easier integration into tools like reviewdog. I have never used that tool, but if anyone is able to get an integration working, feel free to open a Discussion thread about it and let me know!

More config file name options

Last release, I added configuration file naming options to have the yaml extension, i.e. yamlfmt.yaml and yamlfmt.yml. The way I did that made it so you couldn't have config files with extension also be hidden. That is resolved now, so you can have .yamlfmt.yaml etc.

Bug Fixes

Don't write files if there is no diff

Previously, yamlfmt would always write all files set for formatting even when there would be no change. This meant the edited date of the file was always being updated even though nothing was meant to change. That should not happen anymore.

Fix -global_conf not working as documented

The -global_conf flag was not working as documented in the last release. If there was a local config, -global_conf would end up being ignored and the local config would be used first. This was not the intended functionality and it has been fixed.

Contributors

Thanks @kiliantyler for the catching the global configuration bug and opening a fix for it!

1k stars!

Thank you very much for over 1000 stars on GitHub! I appreciate the support, and I hope the tool continues to be useful to the community!

v0.11.0

Oops, all features!

https://www.youtube.com/watch?v=cXBX2PumuBk

It's been a while since the last release! Life has kept me very busy, but since there were a number of feature requests in the issue queue that weren't too challenging to implement I knocked a bunch of them off the list! I also came up with one feature for this release myself.

Config Discovery Enhancements

Two major enhancements to config discovery! I am pretty sure they are purely additive and shouldn't break any existing workflows, but don't hesitate to open an issue if there's something I missed.

Config file can be .yamlfmt, yamlfmt.yaml, or yamlfmt.yml

Instead of forcing the .yamlfmt hidden file name, the command will also recognize yamlfmt.yaml or yamlfmt.yml as a valid file name. (Note that this only applies to automatic config searching; it has never mattered what the name of a file specified directly in the -conf flag is.)

Config file search goes all the way up the directory tree

Instead of only looking for a yamlfmt config in the working directory, it will look at every directory up from the current directory and use the nearest config file it can find. If it doesn't find one all the way up the tree, then it will default to the config file in the global location at $XDG_CONFIG_HOME/yamlfmt (LOCALAPPDATA on Windows). This should be useful for monorepo scenarios, where you might want to apply a single yamlfmt config file to a number of projects within the monorepo, instead of needing a config file in every sub-project or having to manually specify with -conf.

This does change some potential scenarios where previously the global config would have been discovered. To combat this, I added a new command line flag -global_conf that will force using the config from the global location.
Similarly, I added -no_global_conf to force not using the global config.

Use a .gitignore for excludes

The -gitignore_excludes or gitignore_excludes top-level config option will allow yamlfmt to use patterns from a .gitignore file for excluding files from formatting! This should be helpful for scenarios where you previously would have needed to repeat all of these patterns in your own yamlfmt excludes config. You can also specify a specific path to a .gitignore file with -gitignore_path or gitignore_path (command/config respectively).

Retain only single line breaks

Sometimes you have yaml files where there are lots of line breaks in a row. Sometimes you want to keep those, but sometimes you only want to keep a single one out of a group. The new formatter-level config option retain_line_breaks_single will make it so this:

a: 1


b: 2

Formats to this:

a: 1

b: 2

Debug Logging

(This is the one I came up with)

By default yamlfmt is deliberately very quiet on output. This did have a negative though, as even in verbose mode it was hard to figure out which config file was used, or why files may have been excluded/included in formatting. Introducing the -debug command line flag! Currently there are two debug logging profiles:

• The config profile will log the config file discovery process so you can figure out which config file was used and why
• The paths profile will log the include/exclude process to understand exactly which paths are included/excluded and why

Read more about usage in the docs: https://github.com/google/yamlfmt/blob/v0.11.0/docs/command-usage.md#debug-logging

Conclusion

I knocked out a good number of the issues that aren't rooted in the yaml parsing/formatting portion of the tool (only one outlier that I'll address soon). This means my future focus is on how to solve some of the weird yaml problems. Right now it is looking like the main way for me to address these issues is by finally biting the bullet and writing my own. I decided to address a number of features this release to make sure I don't leave open issues out to dry while I dive into this new challenge.

As always, don't hesitate to open an issue if you have any problems!

v0.10.0

I don't have a name for this release

I've waited too long to do this release and there's a couple features that need to get out.

Features

version flag

Now you can print the current yamlfmt version with yamlfmt -version.

continue_on_error flag (#114)

If you would like to continue on error and not exit with code 1 when one of your files aren't formatting, you can use yamlfmt -continue_on_error. The errors will be printed out, but the tool will continue along.

Bug Fixes

Excludes weren't working (#121)

Due to a misunderstanding on my part, I swapped standard filepath collection mode to calculate exclusions using absolute paths. This worked because of the way tests were written, but it does not work in most real world scenarios and it slipped by. This should now be resolved.

Contributors

Thanks @kachick for the version flag! #117
Thanks @koki-develop and @trevorrea for fixing some typos in docs and comments!

v0.9.0

The Content Analyzer Release

Biggest release in a long time! Had lots of spare time to fix some stuff that has been requested for a while, as well as some stuff that came up during the work on this release.

Features

Downgrade to Go 1.18

This is the most disruptive change, although I hope it won't affect anyone too much. Previously, yamlfmt was using Go 1.19 and then Go 1.20. I wasn't actually using any features from Go 1.19, and only errors.Join from Go 1.20. Since I now support installing as a pre-commit hook, and some folks still go through go install to install yamlfmt, I figured it would be in everyone's best interest to support a lower minimum version. I still make use of generics and would like to continue to, so I went with Go 1.18 as the minimum required version.

Better Docs

The docs have been cleaned up quite a bit and should be easier to navigate. I'm still considering moving over to using the GitHub Wiki feature, but right now it's really convenient to have the docs living with the code and there's a chance I might opt for a documentation site instead. I'll keep thinking about this!

Content Analyzer

A new construct has been added in this release, the ContentAnalyzer. This is an interface designed for performing actions based on the contents of the discovered yaml files. In this release, the only action currently possible is excluding yaml files based on their content instead of just exclude patterns. I added two ways to do this.

Metadata

In the yamlfmt library a new construct has been added called Metadata. See the Metadata docs for more information. This was created in this release to support the first type of Metadata, ignore:

# !yamlfmt!:ignore

If this metadata is detected in the document, yamlfmt will exclude it from formatting.

Exclude files by content regex (#101)

The other way is through a new command configuration called regex_exclude. Using Golang regexes, you can now provide a regex for yamlfmt to match with each files contents. For example, if you generate yaml files with a header comment:

# generated by: my awesome tool

You can provide the following regex_exclude:

regex_exclude:
- ".*generated by.*"

This will cause any file with that header comment to be excluded from formatting.

Configure yamlfmt through the CLI (#88)

This one has been requested for a while and I've wanted to do it for a while but never could think of a nice way to do it based on how I'd chosen to implement configuration. I've settled on an implementation that I think will work pretty well, and doesn't rock the boat too much. This should be easier for folks using yamlfmt directly in CI, removing the need for a .yamlfmt file if you'd like not to.

Drop Merge Tags (#102)

yamlfmt used to always add a !!merge tag explicitly:

a: &a
b:
 !!merge <<: *a

This release adds a formatter configuration option called drop_merge_tag, that when true will ensure this tag is excluded:

a: &a
b:
 <<: *a

Pad Line Comments (#104)

By default, yamlfmt will put one space between line contents and the comment on that line. The new formatter configuration option called pad_line_comments will allow you to configure the number of spaces that the yaml library uses to pad line comments.
i.e. with pad_line_comments: 1

a: 1 # comment

And with pad_line_comments: 2

a: 1  # comment

Bug Fixes

Absolute paths in doublestar exclude patterns (#97)

Providing an absolute system path in your exclude patterns would previously not match in most scenarios. This has been fixed, and absolute paths like /home/user/**/ignore_this_file.yaml should work now.

Contributors

Thank you @badouralix for all the new suggestions this release, as well as contributing a bugfix in CLI configuration (#100 which I'm glad was found before release), and the pad_line_comments feature!

---

This ended up being a large release because I had some free time to really catch up on the features I've wanted to include for a while. Now that I've settled up some of these feature gaps, I'm going to spend my time mainly on improving the testing in this repo. I plan on setting up some end-to-end tests to improve my verification of release (which right now is just me running the command a bunch of different ways). I also want to finally properly godoc all the types at least in the main yamlfmt library section. I will still be addressing bugfixes, but feature work may get put on hold unless there's really low-hanging fruit or someone else is willing to contribute them. Thanks as always for using the tool and providing your feedback!

v0.8.0

The Indentless Array Release

The bulk of this release is code cleanup, however there are a couple notable features that have made it in as well!

Features

Indentless Arrays

This was a feature that I've wanted to include since the original release of the tool, however I couldn't make it happen until switching to the yaml library fork. Now that I've done that, I added the functionality to the library and have added a config field indentless_arrays to enable it in yamlfmt!

Quiet Mode

A new CLI flag, -quiet has been added. It only has an effect on Dry Run or Lint. Instead of outputting all the full diffs to the stdout, Quiet Mode will only output the names of the files that had formatting differences.

This work changed the yamlfmt API a bit, primarily in engine. I am not currently aware of anyone relying on the yamlfmt API, but if you are make sure you update yourself to match the new setup. I think it's much better now than it was before.

Bug Fixes

Max Line Length default adjustment

The original default setting for max line length default did not match the intention/what the documentation suggested. It uses the default value of 0, which makes the default line length 80 in the library under the hood. It is supposed to be -1, essentially infinite, by default. This has been fixed.

precommit hook more well formed

The pre_commit hook originally included the . directory as part of the entry. Because precommit actually provides all found files as positional arguments to the entry command, there's no reason to do that. The hook is now more properly formed.

Contributors

Thanks @sangheee for the max line length fix!

---

Thank you very much for over 700 stars! It's really exciting to see my tool getting usage, and I hope that the tool continues to help people.

v0.7.1

Precommit and Bugfix Patch Release

I goofed and needed a patch release. I've copied the v0.7.0 patch notes below to make sure they aren't buried since there's important stuff to note that I don't want to bury.

Bugfixes

Printing all collected paths to stdout

I left in a print I used for debugging that was there for so long I had forgotten it wasn't intentional. 🤕 It's gone now.

Features

pre-commit integration

Since I had to make a patch release, this new pre-commit integration functionality makes it into this patch release. See the section in the README for instructions!

Below is v0.7.0 patch notes.

The Big Path Change Release

This is one of the biggest releases of yamlfmt since the initial! And it's completely my fault because my holidays were so busy that this project unfortunately was lower in my priorities. Lots of new functionality, including one major breaking change (sorry for pulling a v0.x lol).

Major Breaking Change

The yamlfmt command now boasts a new simplified default path specification format. The default mode for path specification is simply directories (searched recursively for files with desired file extensions) or direct paths to files. This is the new default, however the old doublestar glob behaviour can be restored with the -dstar flag or the global doublestar option. See the new configuration docs for more info.

To go with this, issue #71 brought up a good point that it is strange for yamlfmt to automatically search the working directory recursively. Looking at similar formatting tools I am trying to emulate, none of them do this. So I've removed that behaviour; you now have to specify at least one path. I didn't add a switch to restore old behaviour for this, since it seems pretty unlikely to cause much friction. If you disagree, feel free to open an issue.

Features

Using new yaml fork

While this on its own doesn't adjust user-facing functionality, it mostly represents a new direction for the project. This now means I am no longer at the mercy of the underlying yaml library, which is understandably very challenging to get things merged into. Some major things have already been fixed and tech debt reduced with more to come as I get the hang of the codebase.

Emoji support is now default

You can remove emoji_support from your .yamlfmt file, as the functionality for emoji_support is now baked into the yaml library!

You can define a system-wide .yamlfmt config!

This improves the config file resolution to resolve things in priority order. It also includes support for config from a configuration home directory (i.e. $XDG_CONFIG_HOME, $HOME/.config, %LOCALAPPDATA%) so a user can override the default config system-wide. See the config section of the README for updated info.

Set line length

This one was requested for a long time, but couldn't be done until I had control of the yaml library. In the basic formatter you can finally set a line_length option. I don't think the feature is perfect yet, and if you find an edge case let me know and I will see if it's workable.

Preserve line breaks in folded block scalars

Folded block scalars (multiline strings starting with > block specified) previously would have their newlines removed. This was an unfortunate side effect of expected yaml parsing behaviour, since these blocks are supposed to have their newlines squashed on processing. However, for yamlfmt in particular, this is undesirable as we want to retain that line break information on format. I can't decide if this is clever or stupid, but my solution is to add an override that will force folded block scalars to be scanned as if they are literal (|) block scalars, while retaining the fact that they are folded. This seems to work in all cases I could think of, however I decided to lock this behind an option in the basic formatter just in case. The option is scan_folded_as_literal.

Bug Fixes

Exclude paths didn't work with ./

The filepath wasn't cleaned before used as a doublestar pattern, which meant exclude paths with a ./ in front would fail.

Contributors

• Thanks @fsrv-xyz for the Exclude Paths fix!

---

Thank you all for your patience while I got this release out. Since this is only a side project for me I can't dedicate as much time to it as I would like, and end-of-year priorities got in the way. I will try my best not to do a release this big again. If you have any problems or requests, don't hesitate to open an issue!

v0.7.0

The Big Path Change Release

This is one of the biggest releases of yamlfmt since the initial! And it's completely my fault because my holidays were so busy that this project unfortunately was lower in my priorities. Lots of new functionality, including one major breaking change (sorry for pulling a v0.x lol).

Major Breaking Change

The yamlfmt command now boasts a new simplified default path specification format. The default mode for path specification is simply directories (searched recursively for files with desired file extensions) or direct paths to files. This is the new default, however the old doublestar glob behaviour can be restored with the -dstar flag or the global doublestar option. See the new configuration docs for more info.

To go with this, issue #71 brought up a good point that it is strange for yamlfmt to automatically search the working directory recursively. Looking at similar formatting tools I am trying to emulate, none of them do this. So I've removed that behaviour; you now have to specify at least one path. I didn't add a switch to restore old behaviour for this, since it seems pretty unlikely to cause much friction. If you disagree, feel free to open an issue.

Features

Using new yaml fork

While this on its own doesn't adjust user-facing functionality, it mostly represents a new direction for the project. This now means I am no longer at the mercy of the underlying yaml library, which is understandably very challenging to get things merged into. Some major things have already been fixed and tech debt reduced with more to come as I get the hang of the codebase.

Emoji support is now default

You can remove emoji_support from your .yamlfmt file, as the functionality for emoji_support is now baked into the yaml library!

You can define a system-wide .yamlfmt config!

This improves the config file resolution to resolve things in priority order. It also includes support for config from a configuration home directory (i.e. $XDG_CONFIG_HOME, $HOME/.config, %LOCALAPPDATA%) so a user can override the default config system-wide. See the config section of the README for updated info.

Set line length

This one was requested for a long time, but couldn't be done until I had control of the yaml library. In the basic formatter you can finally set a line_length option. I don't think the feature is perfect yet, and if you find an edge case let me know and I will see if it's workable.

Preserve line breaks in folded block scalars

Folded block scalars (multiline strings starting with > block specified) previously would have their newlines removed. This was an unfortunate side effect of expected yaml parsing behaviour, since these blocks are supposed to have their newlines squashed on processing. However, for yamlfmt in particular, this is undesirable as we want to retain that line break information on format. I can't decide if this is clever or stupid, but my solution is to add an override that will force folded block scalars to be scanned as if they are literal (|) block scalars, while retaining the fact that they are folded. This seems to work in all cases I could think of, however I decided to lock this behind an option in the basic formatter just in case. The option is scan_folded_as_literal.

Bug Fixes

Exclude paths didn't work with ./

The filepath wasn't cleaned before used as a doublestar pattern, which meant exclude paths with a ./ in front would fail.

Contributors

• Thanks @fsrv-xyz for the Exclude Paths fix!

---

Thank you all for your patience while I got this release out. Since this is only a side project for me I can't dedicate as much time to it as I would like, and end-of-year priorities got in the way. I will try my best not to do a release this big again. If you have any problems or requests, don't hesitate to open an issue!