YAML/XML/TOML Prettier based on yq

yq is Command-line YAML, XML, TOML processor - jq wrapper for YAML/XML/TOML documents.

That pre-commit-hook was designed, firstly as auto-alphabetize YAML list hooks, but also support usage in raw_yq mode - where you do what you want providing fully custom args to yq.

• How to install
  • 1. Install dependencies
  • 2. Install the pre-commit hook globally
  • 3. Add configs and hooks
  • 4. Run
• Glossary
• Available modes/presets
  • Alphabetization mode
  • Use hook in raw_yq mode
• Authors
• License

Want to contribute? Check open issues and contributing notes.

How to install

1. Install dependencies

• pre-commit, _{^{git, POSIX compatible shell, Internet connection (on first run), x86_64 compatible operation system, Some hardware where this OS will run, Electricity for hardware and internet connection, Some basic physical laws, Hope that it all will work.}}
  
  

• bash 4 or higher

• patch 2.5.8 or higher, 2.7.6+ preferred

• yq OR docker _{^{or both}}

  If both are installed, hook prefers locally installed yq.

MacOS

brew install pre-commit bash yq gpatch

Ubuntu 20.04

sudo apt update
sudo apt install -y unzip software-properties-common python3 python3-pip
python3 -m pip install --upgrade pip
pip3 install --no-cache-dir pre-commit
sudo apt install -y yq

Windows 10/11

We highly recommend using WSL/WSL2 with Ubuntu and following the Ubuntu installation guide.

Note: We won't be able to help with issues that can't be reproduced in Linux/Mac. Please try to find a working solution and send a PR before opening an issue.

Otherwise, you can follow this gist:

1. Install git and gitbash
2. Install Python 3
3. Install all prerequisites needed (see above)

Ensure your PATH environment variable looks for bash.exe in C:\Program Files\Git\bin (the one present in C:\Windows\System32\bash.exe does not work with pre-commit.exe)

2. Install the pre-commit hook globally

Note: not needed if you use the Docker image

DIR=~/.git-template
git config --global init.templateDir ${DIR}
pre-commit init-templatedir -t pre-commit ${DIR}

3. Add configs and hooks

Step into the repository you want to have the pre-commit hooks installed and run:

git init
cat <<EOF > .pre-commit-config.yaml
repos:
- repo: https://github.com/SpotOnInc/pre-commit-yq
  rev: <VERSION> # Get the latest from: https://github.com/SpotOnInc/pre-commit-yq/releases
  hooks:
    - id: yq_yaml_prettier
EOF

4. Run

Execute this command to run pre-commit on all files in the repository (not only changed files):

pre-commit run -a

Glossary

yq PATH - here is PATH to the object inside file, supported by yq.

In example, YAML representation of:

components:
  terraform:
    okta-groups-teleport:

In yq PATH is .components.terraform.okta-groups-teleport.

Available modes/presets

Alphabetization mode

To make all your YAML list in alphabetical order, just add to .pre-commit-config.yaml next:

- repo: <REPO>
  rev: <VERSION> # Get the latest from: <REPO>/releases
  hooks:
    - id: yq_yaml_prettier

If you'd to like specify only one yq PATH which should be alphabetized in the file:

1. Add a flag -s (--sort-path) in args: section

Note: 2. don't work in most cases. That's a bug, which could be fixed by rewriting hook to Python/JS and remove yq at all.

2. In the same line, provide Key=Value, where Key is path to file from repo root, and Value is golang regex which check yq PATH and includes yq PATH'es which pass regex:

- name: Alphabetize YAML arrays
  id: yq_yaml_prettier
  args:
    - -s okta/teleport.yaml=^.components.terraform|name$
    - -s another/file.yml=.foo.bar

Use hook in raw_yq mode

You can provide any valid yq expression:

1. Add a flag -r (--raw-yq) in args: section
2. In the same line, provide inputs for yq

For example, next is identical to hook without any args

- name: Describe here what you do
  id: yq_yaml_prettier
  args:
    - -r -i '( ... |select(type == "!!seq")) |= sort_by( select(tag == "!!str") //  (keys | .[0]) )'

To only display changes, in the example above replace -i with -P.

WARNING: When -r specifued, all -s flags in current hook call will be ignored.

---

Also, you can change on which files you'd like to run hook (default - "any YAML") and which you want exclude.

- id: yq_yaml_prettier
  ...
  files: \.(ya?ml)$
  exclude: |
    (?x)
      # Do not touch pre-commit related files
      (^.pre-commit
      # Fails on YAML-templates extensions
      |^helmfiles
      |/templates/
    )

More about regular expressions in pre-commit you can read here. In two words, that is Python re.VERBOSE.

Authors

This repository is managed by SpotOn OSS team with help from these awesome contributors:

Additional thanks to pre-commit-terraform hooks contributors.

License

MIT licensed. See LICENSE for full details.