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!

v0.6.0

First release in a while! I've been very busy this past month and was also sick for a bit. Not a ton going on this release, but there are some folks waiting for the minor fixes and one feature, so I figured no reason to delay the release.

Features

• Disallow yaml anchors and aliases
  • New basic formatter configuration option disallow_anchors will forcefully reject anchors if you don't want them in your yaml files

Fixes

• Fixed a bug where emoji_support would eat any \ escape character
• Fixed misuse of path package when should have been using filepath package for cross-platform compatibility
• Fixed issue where the tool would try to format a directory if it was picked up the include path

Contributors

• Thanks @imjasonh for their first contribution, the disallow_anchors feature!
• Thanks @longkai for the filepath fix and for adding a GitHub Action to automate releases!

v0.5.0

There was a bug in v0.4.0 caused by my oversight that I previously relied on empty string to represent no diffs. With the more robust reporter this was no longer true. I pulled in an update to the package that provides a diff count from the Diff function and used that instead. While fixing that, I realized that the line separator for the multilinediff also assumed lf line endings, which was basically a bug since the beginning. I fixed it with a rearchitecture that allowed for line_ending to be a global setting. There is a chance I'll decide to adjust this again in the future, but in my current architecture that was the only way to make it work (other than autodetecting the line endings based on OS, but OS does not always imply line endings since there's lots of LF line ending folks on Windows).
It also made sense while doing this to adjust the yamlfmt.Factory interface to simply be one function NewFormatter, and make it so that function handles the case where the passed config is nil.

Changelog

• f0be560 feat: global linesep character, handle diffs (#50)

v0.4.0

This release is smaller than the last few. I wanted to get a release out before I go on leave for a bit.

Changes

emoji_support

This is a combination of a fix and a feature; the yaml.v3 library does not properly parse emojis because it cannot properly print 4-byte UTF-8 characters. Hopefully that gets fixed soon, and #41 is open to track that when it happens. While this would be sensible to make a default behaviour, I've opted to default to false because it is a hack around a shortcoming of the upstream library.

retain_line_breaks

When this is enabled, yamlfmt will keep line breaks instead of deleting them. Similar to emoji_support, I would have liked to make this default but because it's a hack around a shortcoming of the library I'm defaulting it to false as well.

Functional Features architecture

This is an improvement to the API of the Basic Formatter, and features improvements to the base yamlfmt package as well. Previously, there were lots of special conditions tacked on before and after formatting in the Format function of the Basic Formatter, and it was becoming increasingly tangled when the needs of the function expanded. This improves the extensibility of the formatter, which allows for "features" to be created and added to be run as hooks before and after yaml formatting. Future formatters that I write in this package will use it. This marks an improvement to folks forking this tool and adding their own functionality in, provides a nicer basis for folks interested in writing their own formatters, and should hopefully make future contribution a lot more straightforward.

Diff improvement

I've made another improvement to the diff readability. The diff now shows side by side, making it far more easy to read. It still needs some more work, however I've separated that work into a new package that I will from here on incrementally improve in my spare time.

stdout output is more convenient

I had used fmt.Println to output to stdout in previous versions. This caused a problem for folks using yamlfmt as an editor integration, since yamlfmt already appends a newline to the formatted yaml. This release swapped to fmt.Print instead.

If you have any problems or suggestions, feel free to make an issue!

Contributors

Thanks to @longkai for the retaining line break feature and the fix to stdout output.

Changelog

• d9d4189 chore: don't append new line at the end and keep the content as it is (#45)
• f3eff05 engine: switched to multilinediff package (#47)
• e05c99f fix #27 retain line break (#42)
• 9fffda5 fix: line break format issue after refactor code (#44)
• d9e8674 hotfix: add utf-8 parsint for emoji_support (#40)
• 6da562a yamlfmt: added and implemented functional features (#43)

v0.3.0

Features

• Can now operate in stdin mode with the Unix pattern of - or /dev/stdin arguments
• Pass a custom config from another path using the -conf flag

Improvements/Fixes

• Works with CRLF
  • There are a couple bugs upstream that were causing problems with CRLF behaviour, see #34 and #37 for details
• Updated help message

Fixes

Changelog

• 5ad1599 chore: fix indent typo in configuration options (#25)
• 79e66ea feat: accept - or /dev/stdin instead of -in (#28)
• fc7dca4 feat: add ability to pass config path (#30)
• fe69346 feat: improve help message (#32)
• abc4812 fix: hotfix shim for CRLF behaviour (#36)