Metadata-Version: 2.4
Name: yamlruff
Version: 0.0.3
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Quality Assurance
License-File: LICENSE
Summary: Fast YAML linter and fixer, compatible with yamllint
Keywords: yaml,lint,linter,fixer,formatter,yamllint,yamlfix
License: GPL-3.0-or-later
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Repository, https://github.com/lkhagvadorj-amp/yamlruff

# yamlruff

[![PyPI](https://img.shields.io/pypi/v/yamlruff.svg)](https://pypi.org/project/yamlruff/)
[![License](https://img.shields.io/pypi/l/yamlruff.svg)](https://pypi.org/project/yamlruff/)

A fast YAML linter and fixer, written in Rust.

- ⚡️ **Fast**: about 28× faster than existing YAML linters and 13× faster than existing YAML fixers (measured on real-world files).
- 🔧 **Lint and fix in one tool**: `yamlruff lint` reports, `yamlruff fix` repairs, with one shared configuration.
- 🛡️ **Safe fixes**: every fix is checked to leave the loaded data unchanged; files with syntax errors are never touched.
- 📏 **23 built-in rules**: whitespace, indentation, flow collections, comments, quoting, keys and anchors.
- 🐍 **Installable via pip or uv**, as a prebuilt binary: no Python dependencies, no Rust toolchain.
- 🛠️ **`pyproject.toml` support**: configure under `[tool.yamlruff]`, or in a `.yamlruff` file.
- 🧩 **Shareable configs** with `extends`, per-rule `ignore`, and inline `# yamlruff disable` comments.
- 🤖 **CI-friendly**: `--check` for fixes, `-f github` annotations, and clear exit codes.

yamlruff is an independent project, not affiliated with Astral or the ruff project.

---

## Table of Contents

- [Getting Started](#getting-started)
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Rules](#rules)
- [Fixing](#fixing)
- [Continuous integration](#continuous-integration)
- [Contributing](#contributing)
- [Support](#support)
- [License](#license)

## Getting Started

With [uv](https://docs.astral.sh/uv/), no install needed:

```sh
uvx yamlruff lint .        # find problems
uvx yamlruff fix --diff .  # preview the fixes
uvx yamlruff fix .         # apply them
```

Or with pip:

```sh
pip install yamlruff
yamlruff lint .            # find problems
yamlruff fix --diff .      # preview the fixes
yamlruff fix .             # apply them
```

For example, given `service.yml`:

```yaml
name:   web
enabled: yes
ports: [ 80,443 ]
```

`yamlruff lint service.yml` reports the missing `---`, the extra spaces after the colon, the
`yes`, the spaces inside the brackets and the missing space after the comma. `yamlruff fix`
repairs the layout problems right away and leaves the `yes` for `--unsafe-fixes`, because
rewriting it to `true` changes what some YAML loaders read.

## Installation

```sh
uv tool install yamlruff     # or: pipx install yamlruff / pip install yamlruff
```

Run it once without installing with `uvx yamlruff …`. Check the install with
`yamlruff --version`.

Prebuilt wheels exist for macOS (Intel and Apple Silicon) and Linux (glibc and musl; x86_64
and aarch64). On other platforms pip builds from the source distribution and needs Rust.

## Usage

```sh
yamlruff lint [PATHS]...           # report problems ('-' reads stdin; default '.')
yamlruff fix [PATHS]...            # rewrite files, then report what is left
yamlruff rule [ID]                 # list the rules, or document one
```

| Command / option | Effect |
| --- | --- |
| `lint -f standard\|parsable\|colored\|github\|auto` | Output format |
| `lint -s`, `--strict` | Exit non-zero on warnings as well as errors |
| `lint --no-warnings` | Show errors only |
| `lint --list-files` | Show which files would be checked, then exit |
| `fix --diff` | Show the changes, write nothing |
| `fix --check` | Write nothing; exit 1 if any file would change |
| `fix --unsafe-fixes` | Also apply fixes that may change what other loaders read |
| `fix --unfixable ID` | Never apply the fixes of this rule |
| `-c FILE`, `-d 'YAML'` | Use a config file, or config given inline |

## Configuration

yamlruff reads `.yamlruff` (or `.yamlruff.yaml` / `.yamlruff.yml`) from the current directory
and then upward, or a `[tool.yamlruff]` table in `pyproject.toml`. Without either, it uses the
`default` preset; `extends: relaxed` is more lenient.

```yaml
# .yamlruff
extends: default
rules:
  line-length: {max: 120}
  truthy: {check-keys: false}     # keep `on:` as a key in GitHub Actions
  indentation: {spaces: 2, indent-sequences: true}
  trailing-spaces: disable
ignore: |
  dbt_packages/
  target/
```

```toml
# pyproject.toml
[tool.yamlruff.rules]
line-length = { max = 120 }
```

Other top-level keys: `yaml-files` (which files count as YAML), `ignore-from-file`,
`respect-gitignore` (default `false`), `locale`, and the `fix:` section described under
[Fixing](#fixing). Turn rules off inside a file with comments:

```yaml
# yamlruff disable-line rule:line-length
# yamlruff disable rule:truthy
# yamlruff enable rule:truthy
# yamlruff disable-file
```

## Rules

23 rules; `yamlruff rule <id>` shows the options, defaults and what the fix does.

| Rule | Checks | Default | Fix |
| --- | --- | --- | --- |
| `anchors` | Report undeclared aliases, duplicated anchors and unused anchors | error | safe |
| `braces` | Control the spaces inside and the number of items of flow mappings `{...}`, or forbid them | error | safe |
| `brackets` | Control the spaces inside and the number of items of flow sequences `[...]`, or forbid them | error | safe |
| `colons` | Control the spaces before and after `:` in mappings | error | safe |
| `commas` | Control the spaces before and after `,` in flow collections | error | safe |
| `comments` | Require a space after `#` and spaces before an inline comment (a `#!` shebang on the first line can be allowed) | warning | safe |
| `comments-indentation` | Require comments to be indented like the content around them | warning | safe |
| `document-end` | Require or forbid the document end marker `...` | off | safe |
| `document-start` | Require or forbid the document start marker `---` | warning | safe |
| `empty-lines` | Limit the number of consecutive blank lines, and at the start and end of the file | error | safe |
| `empty-values` | Forbid empty values in block mappings, flow mappings and block sequences | off | safe |
| `float-values` | Forbid NaN, infinity, scientific notation and decimals without a leading numeral | off | safe |
| `hyphens` | Limit the spaces after `-` in block sequences | error | safe |
| `indentation` | Control the indentation of blocks, and of sequences inside mappings | error | safe |
| `key-duplicates` | Forbid duplicated keys in a mapping (and optionally repeated `<<` merge keys) | error | unsafe |
| `key-ordering` | Require the keys of a mapping to be in alphabetical order (see `locale`) | off | safe |
| `line-length` | Limit the length of lines | error | safe |
| `new-line-at-end-of-file` | Require a newline at the end of the file | error | safe |
| `new-lines` | Require a given type of line break (`unix`, `dos` or `platform`) | error | safe |
| `octal-values` | Forbid implicit (`0755`) and explicit (`0o755`) octal numbers | off | unsafe |
| `quoted-strings` | Require or forbid quotes around strings, and choose the quote type | off | safe |
| `trailing-spaces` | Forbid spaces at the end of lines | error | safe |
| `truthy` | Forbid values such as `yes` and `on` that are booleans for some YAML versions | warning | unsafe |

Fix: **safe** changes layout only; **unsafe** needs `--unsafe-fixes`. A few cases within a rule
(for example `.nan` in `float-values`, or undeclared aliases) have no fix and only report. Rules that report as *error* fail the run, *warning* rules only with `--strict`.

## Fixing

`yamlruff fix` applies the fix that belongs to each problem, using the rule's own options, so
after a fix `lint` has nothing left to report that could have been fixed automatically.
After every round it checks that the document still loads to the same data, and drops any fix
that would change it. Some problems have no safe automatic fix (a duplicated key with different
values, a line that cannot be wrapped) and stay in the report.

Pure style choices that no rule expresses go in a `fix:` section:

```yaml
fix:
  sequence-style: flow         # keep | flow | block
  none-representation: empty   # keep | empty | null | '~' | Null | NULL
  whitelines: 1                # blank lines between content
  comments-whitelines: 1       # blank lines before a comment
  section-whitelines: 1        # blank lines around top-level sections
  join-multiline: false        # put multi-line scalars on one line when they fit
  simplify-block-headers: false
  unsafe-fixes: false
  unfixable: []                # rule ids whose fixes are never applied
```

## Continuous integration

```sh
yamlruff lint --strict .       # fail the build on any problem
yamlruff fix --check .         # fail if formatting would change anything
yamlruff lint -f github .      # annotate the pull request in GitHub Actions
```

Exit codes for `lint`: `0` clean, `1` errors, `2` warnings only (with `--strict`).

## Contributing

Bug reports, ideas and pull requests are welcome. See [CONTRIBUTING.md](https://github.com/lkhagvadorj-amp/yamlruff/blob/main/CONTRIBUTING.md) for
how to build, test and release.

## Support

Open an issue on the [repository](https://github.com/lkhagvadorj-amp/yamlruff/issues) with the
`yamlruff --version`, the command you ran, and a minimal YAML file that shows the problem.

## License

This repository is licensed under the [GPL-3.0-or-later License](https://github.com/lkhagvadorj-amp/yamlruff/blob/main/LICENSE).

