{"id":22824378,"url":"https://github.com/opt-nc/yamlfixer","last_synced_at":"2025-08-21T13:32:54.801Z","repository":{"id":37937628,"uuid":"436478502","full_name":"opt-nc/yamlfixer","owner":"opt-nc","description":"Automates the fixing of problems reported by yamllint by parsing its output","archived":false,"fork":false,"pushed_at":"2024-01-30T13:43:56.000Z","size":653,"stargazers_count":50,"open_issues_count":32,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-04-23T23:38:51.016Z","etag":null,"topics":["automation","cli","command-line","devops","devops-tools","fixer","lint","linter","yaml","yamllint"],"latest_commit_sha":null,"homepage":"https://dev.to/adriens/series/18168","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/opt-nc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-09T04:10:53.000Z","updated_at":"2024-03-06T17:09:49.000Z","dependencies_parsed_at":"2024-12-12T17:17:54.750Z","dependency_job_id":null,"html_url":"https://github.com/opt-nc/yamlfixer","commit_stats":{"total_commits":349,"total_committers":6,"mean_commits":"58.166666666666664","dds":"0.21203438395415475","last_synced_commit":"0ce16e032d7348e996d00abb0ad79b9df610f5ef"},"previous_names":[],"tags_count":73,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opt-nc%2Fyamlfixer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opt-nc%2Fyamlfixer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opt-nc%2Fyamlfixer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opt-nc%2Fyamlfixer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opt-nc","download_url":"https://codeload.github.com/opt-nc/yamlfixer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230516183,"owners_count":18238352,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","cli","command-line","devops","devops-tools","fixer","lint","linter","yaml","yamllint"],"created_at":"2024-12-12T17:06:28.059Z","updated_at":"2024-12-20T00:08:45.127Z","avatar_url":"https://github.com/opt-nc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![License](https://img.shields.io/github/license/opt-nc/yamlfixer) ![Build](https://img.shields.io/github/workflow/status/opt-nc/yamlfixer/Checks)\n\n[![Docker Image](https://img.shields.io/badge/docker-homepage-blue)](https://hub.docker.com/r/optnc/yamlfixer)\n\n![PyPI](https://img.shields.io/pypi/v/yamlfixer-opt-nc)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/yamlfixer-opt-nc)\n![PyPI - Downloads](https://img.shields.io/pypi/dm/yamlfixer-opt-nc)\n\n# ![yamlfixer's logo](https://github.com/opt-nc/yamlfixer/blob/main/logo/candidates/1-64x64.png) `yamlfixer`\n\n# ❔ About\n\n[yamlfixer](https://github.com/opt-nc/yamlfixer) automates the fixing\nof problems reported by\n[yamllint](https://github.com/adrienverge/yamllint) by parsing its\noutput.\n\n# 🖼️  Screenshot\n\nHere'a screenshot of yamlfixer launched on [yaml-test-suite](https://github.com/yaml/yaml-test-suite) :\n\n![yamlfixer's screenshot](https://github.com/opt-nc/yamlfixer/blob/main/images/screenshot-manyfiles.png)\n\n# 📑 Installation\n\nThe easiest way to install `yamlfixer` is from\n[pypi](https://pypi.org/project/yamlfixer-opt-nc/), as described\nbelow.\n\n\n## 🐧 Linux install\n\n```shell\npython3 -m pip install yamlfixer-opt-nc\n```\n\n## 🪟  Windows install\n\n```shell\npython -m pip install yamlfixer-opt-nc\n```\n## `pipx` setup\n\nFor an optimal experience we recommand using [`pipx`](https://pypa.github.io/pipx/).\n\nTo install : \n\n```shell\npipx install yamlfixer-opt-nc\npipx list\n```\n\nTo upgrade : \n\n```shell\npipx upgrade yamlfixer-opt-nc\n```\n\nTo uninstall :\n\n```\npipx uninstall yamlfixer-opt-nc\n```\n\n# 🚀 Usage\n\nThis software automatically fixes some errors and warnings reported by\n`yamllint`.\n\n```shell\nusage: yamlfixer [-h] [-v] [-b] [-B BACKUPSUFFIX] [-d] [-D DIFF_FILE] [-e EXTENSIONS] [-f]\n                 [-F] [-l] [-N] [-n] [-r LEVEL] [-j | -p | -s] [-t TABSIZE]\n                 [-c CONFIG_FILE | -C CONFIG_DATA]\n                 [FILE_or_DIR [FILE_or_DIR ...]]\n\nFix formatting problems in YAML documents. If no file is specified, then reads input from `stdin`.\n\npositional arguments:\n  FILE_or_DIR           the YAML files to fix. Use `-` to read from `stdin`.\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -v, --version         display this program's version number and exit.\n  -b, --backup          make a backup copy of original files.\n  -B BACKUPSUFFIX, --backupsuffix BACKUPSUFFIX\n                        sets the suffix for backup files, `.orig` is the default.\n  -d, --debug           output debug information to stderr.\n  -D DIFF_FILE, --diffto DIFF_FILE\n                        name of the file a unified diff will be written to.\n                        Defaults to `/dev/null`.\n  -e EXTENSIONS, --ext EXTENSIONS\n                        comma separated list of acceptable extensions when searching directories\n                        for YAML files. Defaults to `yaml,yml,yamllint`.\n  -f, --forcecolors     force colorized output even if stream is not a TTY.\n  -F, --followsymlinks  follow symbolic links when recursing directories.\n  -l, --listfixers      output the list of available fixers.\n  -N, --nosyntax        don't try to fix syntax errors.\n  -n, --nochange        don't modify anything.\n  -r LEVEL, --recurse LEVEL\n                        sets the maximum recursion level for directories. Default is `0` meaning\n                        no recursion, and any negative value means no limit.\n  -j, --jsonsummary     output JSON summary to stderr.\n  -p, --plainsummary    output plain text summary to stderr.\n  -s, --summary         output colorized plain text summary to stderr. If stderr is not a TTY\n                        output is identical to --plainsummary unless --forcecolors is also used.\n  -t TABSIZE, --tabsize TABSIZE\n                        sets the number of spaces to replace tabs with, default is `2`.\n  -c CONFIG_FILE, --config-file CONFIG_FILE\n                        path to yamllint's custom configuration file, none by default.\n  -C CONFIG_DATA, --config-data CONFIG_DATA\n                        custom configuration for yamllint as YAML source, none by default.\n```\n\nyamlfixer launches `yamllint` on each specified filename, then parses\nits output and tries to fix the reported problems. The special\nfilename `-` means `stdin`, and is assumed if there's no other\nfilename argument.\n\nIf input is read from `stdin`, the corrected output will be sent to\n`stdout`.\n\nOther files will be overwritten if needed. Original files, `stdin`\nexcepted, can be preserved as `.orig` if the `--backup` command line\noption is used. You can specify any other backup filename suffix with\nthe `--backupsuffix` command line option.\n\nBoth summaries and diagnostic information are sent to stderr.\n\nThis command exits with status `2` if there are incompatible command\nline options. It exits with `-2` if yamllint is not available on your\nsystem. Otherwise it exits with `0` if all input files either are\nskipped, entirely fixed, or already successfully passed `yamllint`\nstrict mode before, else `-1`.\n\nFor convenience, all or parts of the command line arguments can be\nread from a file, one per line, by using the well known `@argsfile`\nsyntax. For example you could do something like this :\n\n```shell\n$ find . -type f -name \"*.yml\" \u003elist-of-yaml-files\n$ yamlfixer --nochange --summary @list-of-yaml-files\n```\n\nAlthough this could probably be shortened to :\n\n```shell\n$ yamlfixer --nochange --summary --recurse -1 .\n```\n\n**IMPORTANT:** Not all problems are fixable by `yamlfixer`. Due to the\nfact that `yamllint` doesn't currently report all faulty lines,\n`yamlfixer` might even introduce indentation problems under some\ncircumstances.\n\n⚠️**Use at your own risk, you have been warned...** ⚠️\n\n# ✍️ Blogging\n\nYou can find dedicated ressources on `yamlfixer` on : \n\n- [Dedicated series on DEV.to](https://dev.to/adriens/series/18168)\n\n# :octocat: GitHub Action\n\nYou can now use this software as a GitHub Action, available from https://github.com/opt-nc/yamlfixer-action .\nThis GitHub Action will automatically create Pull Requests to your repository with the changes made by yamlfixer.\n\n# ✔️ Fixers\n\n`yamlfixer` currently (as of [`0.9.11`](https://github.com/opt-nc/yamlfixer/releases/tag/0.9.11)) can fix\nthe following problems as reported by `yamllint` :\n\n- comment not indented like content (comments-indentation)\n- found forbidden document end\n- found forbidden document start\n- line too long\n- missing document end\n- missing document start\n- missing starting space in comment (comments)\n- no new line character at the end of file\n- syntax error: could not find expected ':' (syntax)\n- syntax error: expected `'\u003cdocument start\u003e'`, but found `'\u003cstream end\u003e'` (syntax)\n- syntax error: expected `\u003cblock end\u003e`, but found `'\u003cblock mapping start\u003e'`\n- syntax error: expected `\u003cblock end\u003e`, but found `'\u003cblock sequence start\u003e'` (syntax)\n- syntax error: expected `\u003cblock end\u003e`, but found `'?'`\n- syntax error: found character '\\t' that cannot start any token (syntax)\n- syntax error: mapping values are not allowed here\n- too few spaces after comma (commas)\n- too few spaces before comment (comments)\n- too few spaces inside empty brackets (brackets)\n- too few spaces inside brackets\n- too many blank lines\n- too many spaces after colon (colons)\n- too many spaces after comma (commas)\n- too many spaces after hyphen (hyphens)\n- too many spaces before colon (colons)\n- too many spaces before comma (commas)\n- too many spaces inside braces (braces)\n- too many spaces inside brackets (brackets)\n- too many spaces inside empty brackets (brackets)\n- trailing spaces (trailing-spaces)\n- truthy value should be one of [false, true] (truthy)\n- wrong indentation: expected\n- wrong new line character: expected \\\\n\n- wrong new line character: expected \\\\r\\\\n\n\nAn always up-to-date list of fixers can be obtained with `yamlfixer --listfixers`.\n\n☝️ Please read our [TODO list](https://github.com/opt-nc/yamlfixer/blob/main/TODO.md)\nto see which problems are still unsupported but which we plan to support some day.\n\n**IMPORTANT : fixing syntax errors is done on a best effort basis and\nmay work only partially or not at all for you. Use the -N|--nosyntax\ncommand line switch do prevent `yamlfixer` from trying to fix syntax\nerrors.**\n\n# 🎬 Demo\n\nClick on the white triangle in the image below to view a short video demonstration:\n\n[![asciicast](https://asciinema.org/a/478928.svg)](https://asciinema.org/a/478928)\n\n# 💪 Tips and tricks\n\nFind here a set of tips \u0026 tricks about how to achieve great things.\n\nDon't find the usecase you're looking for ➡️ [🎫 Fill a dedicated issue so we could share your idea with the comunity](https://github.com/opt-nc/yamlfixer/issues/new?assignees=\u0026labels=help+wanted\u0026template=ask-for-command-line-script---.md\u0026title=Request+for+script+or+oneLiner)\n\n## ⏩ One liners\n\nMost of us love short and efficient command lines. Here are some ready to use ones : \n\n### Piping `json` summary through `jq`\n\n```\nyamlfixer --jsonsummary examples/good.yml 2\u003e\u00261 | jq\n```\n\nSo you can get a nicely colorized (and validated `json` output) : \n\n```json\n{\n  \"filestofix\": 1,\n  \"passed\": 1,\n  \"modified\": 0,\n  \"fixed\": 0,\n  \"skipped\": 0,\n  \"notwritable\": 0,\n  \"unknown\": 0,\n  \"nochangemode\": false,\n  \"details\": {\n    \"examples/good.yml\": {\n      \"numericstatus\": 0,\n      \"status\": \"PASSED\",\n      \"issues\": 0,\n      \"handled\": 0\n    }\n  }\n}\n```\n\n### Check if `yamlfixer` could fix a `yaml` and get the exit code\n\nSee how to produce a patch file without modifying the original one,\nand get the exit code so you can go further in automation :\n\n```shell\n$ yamlfixer --nochange --summary --diffto my.patch examples/bad.yml\nFiles to fix: 1\n0 files were already correct before\n0 files were modified but problems remain\n1 files were entirely fixed\n0 files were skipped\n0 files were not writable\n0 files with unknown status\n      FIXED examples/bad.yml (handled 4/4)\nWARNING: No file was modified per user's request !\n\n$ echo $?\n0\n\n$ cat my.patch\ndiff -u \"examples/bad.yml\" \"examples/bad.yml-after\"\n--- \"examples/bad.yml\"\n+++ \"examples/bad.yml-after\"\n@@ -1,4 +1,4 @@\n-\n+---\n name: Build HelloYaml\n\n # yamllint disable-line rule:truthy\n@@ -17,6 +17,4 @@\n           cache: 'maven'\n\n       - name: Build with Maven\n-          run: mvn package\n-\n-\n+        run: mvn package\n$ \n```\n\nYou can then manually apply the patch file to modify `examples/bad.yml` if\nthat's what you want to do :\n\n```shell\n$ patch -p0 \u003cmy.patch\npatching file examples/bad.yml\n$\n```\n\nBut of course, it would have been simpler to not use the `--nochange`\ncommand line option in the first place, so that the file would have\nbeen fixed automatically.\n\n# 🧰 Single purpose tools worth knowing\n\n- [`ytt`](https://carvel.dev/ytt/) : _\"YAML templating tool that works on YAML structure (instead of text).\"_\n- [`jq`](https://stedolan.github.io/jq/) : _\"lightweight and flexible command-line JSON processor.\"_\n- [`vimdiff`](https://www.tutorialspoint.com/vim/vim_diff.htm) : _\"edit two, three or four versions of a file with Vim and show differences\"_\n- [`icdiff`](https://www.jefftk.com/icdiff) : _\"improved colored diff \"_\n- [`gomplate`](https://gomplate.ca/) : _\"A flexible commandline tool for template rendering. Supports lots of local and remote datasources.\"_\n\n# 🔖 Related contents\n\n- [Dedicated Post explaining how we are using this project to automate `yaml` linting and fixing](https://dev.to/adriens/let-ci-check-fix-your-yamls-kfa)\n- [GH Action relying on this project](https://github.com/marketplace/actions/yaml-fixer)\n- [Dedicated Katacoda scenario](https://www.katacoda.com/opt-labs/courses/devops-tools/yamlfixer) so you can see it live\n- [Yamlfixer video intro (French, 15')](https://youtu.be/_FiVaMFITkI)\n- [From `cli` to community DEV.to blog post](https://dev.to/adriens/we-wanted-to-create-a-tool-to-fix-yamlsthen-we-got-a-community-42ji) to better understand `yamlfixer inception, history`and roadmap\n\n# 📖 Licensing information\n\n```\nCopyright (C) 2021-2022 OPT-NC\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n```\n\n# 🧑‍🤝‍🧑 Contributing\n\nYou can contribute to this project by [filing an issue](https://github.com/opt-nc/yamlfixer/issues)\nor by [sending a pull request](https://github.com/opt-nc/yamlfixer/pulls)\n\nPlease read our [contributing guidelines](https://github.com/opt-nc/yamlfixer/blob/main/CONTRIBUTING.md)\nbefore.\n\n\n# 🧑‍🤝‍🧑 Contact\n\nTo contact the [authors](AUTHORS.md) of this software, simply fill an\nissue on this project.\n\nOPT-NC, aka _Office des Postes et Télécommunications de Nouvelle-Calédonie_, check\n[`OPT-NC`](https://github.com/opt-nc) Github Organization page for more.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopt-nc%2Fyamlfixer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopt-nc%2Fyamlfixer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopt-nc%2Fyamlfixer/lists"}