Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/itprokyle/pre-commit-hook-yamlfmt
YAML formatter for http://pre-commit.com
https://github.com/itprokyle/pre-commit-hook-yamlfmt
pre-commit
Last synced: 16 days ago
JSON representation
YAML formatter for http://pre-commit.com
- Host: GitHub
- URL: https://github.com/itprokyle/pre-commit-hook-yamlfmt
- Owner: ITProKyle
- License: mit
- Created: 2022-01-18T13:36:27.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2024-12-09T05:20:34.000Z (25 days ago)
- Last Synced: 2024-12-10T11:56:34.878Z (23 days ago)
- Topics: pre-commit
- Language: Python
- Homepage:
- Size: 647 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# YAML formatter for pre-commit git hooks
[](https://github.com/ITProKyle/pre-commit-hook-yamlfmt/actions/workflows/on-push.yml)
[](https://github.com/pre-commit/pre-commit)
[](https://github.com/ITProKyle/pre-commit-hook-yamlfmt/releases)
[](https://developer.mend.io/)
> [!NOTE]
> This project is a fork of [jumanjihouse/pre-commit-hook-yamlfmt](https://github.com/jumanjihouse/pre-commit-hook-yamlfmt).
YAML formatter for [`pre-commit`].
This hook formats the indentation of YAML files and optionally aligns top-level colons.
[`ruamel.yaml`] is used to roundtrip YAML files, preserving comments as much as possible.
> [!IMPORTANT]
> Each versioned release of this hook is pinned to an exact version of it's direct dependencies to limit unexpected changes.
## Options
| Option | Default | Description |
| -------------------------------------------- | ------------------------ | --------------------------------------------------- |
| `--allow-duplicate-keys/--no-duplicate-keys` | `--allow-duplicate-keys` | whether to allow duplicate keys |
| `--colons/--no-colons` | `--no-colons` | whether to align top-level colons |
| `--implicit-start/--no-implicit-start` | `implicit-start` | whether to remove the explicit document start |
| `--mapping, -m` | `4` | number of spaces to indent mappings (dictionaries) |
| `--offset, -o` | `4` | number of spaces to offset the dash from sequences |
| `--preserve-quotes/--no-preserve-quotes` | `--preserve-quotes` | whether to keep existing string quoting |
| `--sequence, -s` | `6` | number of spaces to indent sequences (arrays/lists) |
| `--width, -w` | `4096` | maximum line width |
> [!CAUTION]
> If trying to use `--allow-duplicate-keys` to enable unpacking two anchors into a mapping (dictionary), this will not have the desired result.
> In fact, it can cause breakage without warning other than [`pre-commit`] showing the file was changed.
>
> When used with this scenario, the first anchor will remain but all other anchors will be removed.
> This is a flaw in [`ruamel.yaml`], not this hook.
## How-to
### Configure pre-commit
#### Use defaults
Add to `.pre-commit-config.yaml` in your git repo:
```yaml
- repo: https://github.com/ITProKyle/pre-commit-hook-yamlfmt
rev: v0.2.1 # or specific tag
hooks:
- id: yamlfmt
```
> [!TIP]
> If a pre-commit hook changes a file, the hook fails with a warning that files were changed.
Given this input:
```yaml
foo:
bar:
- baz1
- baz2
```
The default settings result in this output:
```yaml
---
foo:
bar:
- baz1
- baz2
```
#### Combine with `yamllint`
`yamlfmt` only works with valid YAML files, so I recommend to use `yamllint` and `yamlfmt` together.
```yaml
- repo: https://github.com/adrienverge/yamllint.git
rev: v1.21.0 # or higher tag
hooks:
- id: yamllint
args: [--format, parsable, --strict]
- repo: https://github.com/ITProKyle/pre-commit-hook-yamlfmt
rev: v0.2.1 # or specific tag
hooks:
- id: yamlfmt
```
#### Override defaults
Add to `.pre-commit-config.yaml` in your git repo:
```yaml
- repo: https://github.com/ITProKyle/pre-commit-hook-yamlfmt
rev: v0.2.1 # or specific tag
hooks:
- id: yamlfmt
args: [--mapping, '2', --sequence, '2', --offset, '0', --colons, --width, '150']
```
### Invoke pre-commit
#### On every commit
If you want to invoke the checks as a git [`pre-commit`] hook, run:
```console
# Run on every commit.
pre-commit install
```
#### On demand
If you want to run the checks on-demand (outside of git hooks), run:
```console
# Run on-demand.
pre-commit run --all-files
```
## FAQs
### Can I use `pip` to install this?
No. It is strictly a [`pre-commit`] hook.
### Is this project related to [`yamlfmt`](https://pypi.org/project/yamlfmt/)?
No.
[`pre-commit`]: http://pre-commit.com
[`ruamel.yaml`]: https://yaml.readthedocs.io/en/latest/