Configuration v2

A bit of an RFC

Issues

There’s some “problems” with the current configuration and I’d like to address those in a backwards incompatible way (probably through a migration period where both formats are allowed).

There’s two primary issues I’d like to address with the current configuration format:

• The top level is currently a list, making it difficult to add repository-level configuration: #240 #281 (as well as other things I’d like such as repository-level interpreter version)
• The configuration is not scriptably rewriteable: #210

There’s also auxiliary issues:

• yaml is not maintained
• yaml has some security issues #396
• hooks.yaml isn’t well namespaced

Proposal

A new configuration language

I shopped around for configuration languages which fit the criteria above, notably:

• Provides a non-C implementation
• Supports comments + maps + lists
• Supports round-trip rewritability
• Has a python implementaiton

And did not find anything. Given that, I’ve started speccing and implementing a configuration language with those design goals in mind. It also aims to be significantly simpler than yaml (the spec may not fit on a postcard like json, but it’s also not 70+ pages like yaml).

New filenames

The names of the files will need to change for two reasons:

• The configuration will no longer be yaml
• hooks.yaml is not a namespaced-enough name

Proposing:

• .pre-commit-config - describes the consumer configuration (previously .pre-commit-config.yaml)
• .pre-commit-manifest - describes the repository configuration (previously hooks.yaml)

New configuration structure

The new configuration structure will be a top-level mapping type to allow repository-wide configuration. This map will have a hooks key which will contain the current configuration.

hooks: [
        ...,
]

This will allow for top-level configuration which will apply to all hooks (such as global excludes, interpreter versions, etc.)

Migration

• The new configuration will be introduced.
• In that release and the next two releases (or the next 3 months, whichever comes sooner), pre-commit will load both configuration formats but issue warnings for the legacy format.
• After the migration period, the old configuration format will be purged.

The “officially” maintained repositories (pre-commit/pre-commit-hooks as well as the mirrors-* repositories) will force-push tags for the lastest $n versions and provide both configuration formats for those tags. Going forward, pre-commit/pre-commit-mirror-maker will only produce the new configuration format.

To assist in migration (though the formats should be relatively easy to manually migrate) a tool will be created pre-commit-migrate which will attempt to take the legacy format and produce new configuration files. Given yaml’s lack of rewritability this will likely reformat lists and drop comments, but for the last time!

Thoughts?

[bpicolo]

Which part of requirements does https://github.com/toml-lang/toml fail on, out of curiosity? No version that doesnt strip comments?

[Lucas-C]

I don’t want to look too pessimistic, but it looks really ambitious to me to define a new configuration format just for this use case. That means a lot more complexity indirectly added to the project, and giving to the end user a less user-friendly experience (“what ? another language to learn ?”).

Given your criterias, “good old .ini files” could do the job here. Why not contributing to the whole community and adding support for comments round trip into Python ConfigParser instead ?

Alternatively, have you considered commentjson or something similar ?