Managed files

odoo-nix sync --write writes the files below for the modules that are on, and sync --check reports any that differ. A module that turns off takes its files back out.

The files

"Overridable" means an org profile's templates/ may replace the template (Profiles).

The kinds

• Whole: the file is odoo-nix's. It starts with a header comment. A file with a local region says odoo-nix:managed — generated by odoo-nix (`odoo-init --sync`); edit only inside the odoo-nix:local region., and anything you add goes in that region, between odoo-nix:local-begin <name> and odoo-nix:local-end <name>, which sync carries over byte for byte. A file without one (.pylintrc, .pylintrc-mandatory, prettier.config.cjs, eslint.config.cjs, .github/zizmor.yml, the workflow callers) says odoo-nix:managed — generated by odoo-nix (`odoo-init --sync`); do not edit. and takes no additions. Any edit outside a local region is drift.

• Block: odoo-nix owns the lines between >>> odoo-nix: <name> (managed) >>> and <<< odoo-nix: <name> (managed) <<< (<!-- odoo-nix:begin <name> --> in Markdown) and nothing else in the file. A hand-written line the block now covers is absorbed into it on first opt-in when it is identical to the block's (a .gitignore line, an odoo-nix.url in flake.nix that already names the same URL), and a comment paragraph left empty by that goes too. A flake.nix input defined otherwise is refused instead (see First opt-in).

• Merge (TOML, JSON, JSONC): odoo-nix owns the keys it writes and leaves every other one, its order and its comments alone. A pin you raised by hand in tools/pyproject.toml or package.json stays (a lower one is raised); a tool you added stays. JSONC files keep their indent, their inline arrays and a missing final newline.

• Seed: written when missing, never rewritten.

• Lock: tools/uv.lock and package-lock.json are checked against their manifests. --check reports a stale lock (exit 1); --write reruns the lock command; --write --offline names it and runs nothing. Dependabot never moves them: the series data does (Versioning).

Every hook in .pre-commit-config.yaml is language: system and runs a locked tool, never one from PATH: tools/.venv/bin/<tool> (from tools/uv.lock), node_modules/.bin/<tool> (from package-lock.json) or tools/.bin/<tool> (actionlint, zizmor, shellcheck, nixfmt, statix, deadnix, committed: the Nix tools of the odoo-nix the checkout pins). The dev shell links all three into the checkout and runs prek install -c .pre-commit-config.yaml; -c keeps prek from running a nested config of an addon.

First opt-in

A checkout often has files of its own where odoo-nix writes. For these sync refuses to replace yours on first opt-in, exits 2 and prints the diff with where your lines go:

Move them, then rerun with --force. A file odoo-nix's own scaffolding wrote (odoo-init's .envrc) is replaced without asking.

Retire rules

Files another tool's era left, deleted by sync while their module is on (retire-keep in the table keeps one):

An org profile adds its own with [[retire]].

Checks

Beside the files, sync --check (and the end of --write) reports these as drift (exit 1):

• readme with required: an installable addon without README.md or README.rst;

• ci in a project: a .gitmodules entry that does not follow branch = <series>;

• packaging in addons mode: an addon without its whool pyproject.toml, or a nix/uv.lock that predates one (odoo project relock);

• python-lint: a [tool.ruff] table in the config file, which ruff ignores once .ruff.toml exists;

• the series sources disagreeing: .odoo-series (or flake.nix), the manifests' versions, flake.lock's ocb branch, an integration branch named <n>.0 that names another series.

Notices, which change no exit code: releases or packaging on in a project; ruff in the config file's [dependency-groups].dev (the hooks and the editor use the locked one); with ide on, python-envs.* in .vscode/settings.json (it overrides the interpreter); both shapes' signals without an explicit shape.

Refused before anything is written (exit 2): a series odoo-nix-tools has no data for; no tracked flake.nix; an addon repository without its addons-mode nix/pyproject.toml; the table in the other shape's file; addons.lockDir other than "nix"; releases with commits.convention = "odoo"; an [[tool.odoo-nix.untested]] entry naming no addon of the repository; releases under develop+series on a repository whose integration branch is itself a series branch (create develop and make it the default branch first).

Where odoo-nix changes OCA's rules

The lint and format rules are OCA's own, per series, from the series data each odoo-nix-tools release ships (odoo-nix data-path series/18.0.json). Every change odoo-nix makes to them is one of these deviations, applied in code and tested one by one:

With addon-manifest.website = "" the oca-fix-manifest-website hook is not rendered at all.