Commit your repo’s version policy to zerv.toml once. Shared by version and flow; CLI flags still win.
Commit your repo’s stable version policy to a zerv.toml once instead of repeating the same
flags on every zerv invocation.
Discovery
zerv walks up from the current directory to the nearest VCS repository root (Git’s .git
today) and reads zerv.toml there, or the hidden .zerv.toml fallback. Config is
repo-scoped: one policy per repo, no subdirectory shadowing, so a version never depends
on which directory you run from.
# Commit a zerv.toml at your repo root (stable fields only)cat > zerv.toml <<'EOF'source = "stdin"output_template = "v{{ major }}.{{ minor }}.{{ patch }}"EOF# zerv reads zerv.toml automatically; no flags repeated# (stdin carries the version payload; in a git repo use source = "git")zerv version# → v1.2.3# Shared-top fields shape flow toozerv flow --schema standard# → v1.2.3# A CLI flag still wins over the filezerv version --output-template "release-{{ major }}"# → release-1
--config-file <path> reads that file instead of discovering zerv.toml; the
discovered file is never read. Pass the null device to disable config entirely: the empty
file yields no overrides, restoring builtin behavior. There is no --no-config flag; the
null device is the escape hatch (/dev/null on Unix and macOS, NUL on Windows).
# An explicit --config-file is read instead of discovering zerv.tomlcat > explicit.toml <<'EOF'source = "stdin"output_template = "EXPL{{ major }}"EOFzerv --config-file ./explicit.toml version# → EXPL1# The null device disables all config (the empty file yields no overrides).# /dev/null on Unix and macOS, NUL on Windows.zerv --config-file /dev/null version# → 1.2.3
File structure
Stable fields live at the shared top (apply to both subcommands); [version] and [flow]
sections override per-subcommand:
# shared top: applies to every subcommandsource = "stdin"output_format = "semver"output_template = "v{{ major }}.{{ minor }}.{{ patch }}"schema = "standard-context"[version] # optional: override the shared schema for `version` onlyschema = "standard-no-context"[flow] # flow-only stable policypost_mode = "tag"pre_release_label = "beta"hash_branch_len = 7
output_prefix and output_template conflict: they cannot both be set. Put the prefix
directly in the template ("v{{ major }}..."), or use output_prefix with output_format
and no template.
Ephemeral per-build fields (--dirty, --bump-minor, --major, …) are not allowed in
the file: a typo’d or stale key fails loud at parse (deny_unknown_fields) rather than
shipping silently on the next CI run.
Last modified on August 25, 2026
{"docsConfig":{"theme":"mint","$schema":"https://www.mintlify.com/docs.json","name":"zerv","description":"Dynamic versioning from git. Every commit gets its version.","colors":{"primary":"#F59E0B","light":"#F59E0B","dark":"#FBBF24"},"logo":{"light":"https://mintcdn.com/zerv/Ak0rLTc0jknhvwpO/img/brand/zerv-lockup.svg?fit=max\u0026auto=format\u0026n=Ak0rLTc0jknhvwpO\u0026q=85\u0026s=53561e784924d81ab5bceaa553c35e12","dark":"https://mintcdn.com/zerv/Ak0rLTc0jknhvwpO/img/brand/zerv-lockup-dark.svg?fit=max\u0026auto=format\u0026n=Ak0rLTc0jknhvwpO\u0026q=85\u0026s=1b3994d4bed2429b0e5fd30c8ff4e20e"},"favicon":"https://mintcdn.com/zerv/Ak0rLTc0jknhvwpO/img/brand/favicon.ico?fit=max\u0026auto=format\u0026n=Ak0rLTc0jknhvwpO\u0026q=85\u0026s=02de3866958860cec010fa99b8203502","background":{"color":{"light":"#F7F5F0","dark":"#12212A"}},"navbar":{"links":[{"href":"https://github.com/wislertt/zerv","label":"GitHub"}]},"footer":{"socials":{"github":"https://github.com/wislertt/zerv"},"links":[{"header":"Resources","items":[{"label":"PyPI","href":"https://pypi.org/project/zerv-version"},{"label":"crates.io","href":"https://crates.io/crates/zerv"},{"label":"zerv-flow demo","href":"https://github.com/wislertt/example-zerv-flow"},{"label":"Made by Wisaroot Lertthaweedech","href":"https://wisl.dev"}]}]},"seo":{"metatags":{"canonical":"https://zerv.wisl.dev","og:image":"https://zerv.wisl.dev/img/brand/og-card-light.png","twitter:card":"summary_large_image"},"organization":{"url":"https://zerv.wisl.dev","sameAs":["https://github.com/wislertt/zerv","https://pypi.org/project/zerv-version/","https://crates.io/crates/zerv","https://wisl.dev"]}},"styling":{"codeblocks":{"theme":{"light":"github-light","dark":"github-dark"}},"latex":false},"metadata":{"timestamp":true},"markdown":{"instructions":["zerv is a CLI tool that generates version strings from Git state. It is not a service or platform.","Examples on this site are backed by integration tests; copy them verbatim.","Flag names are exact: use --output-template, and --dirty takes no value."]},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"zerv","hasAudioNarration":false,"actualSubdomain":"zerv","customDomains":["zerv.wisl.dev"],"gitSource":{"type":"github","owner":"wislertt","repo":"zerv","deployBranch":"main","contentDirectory":"docs","isPrivate":false,"mountPath":"","label":""},"entitlements":{},"buildId":"6aead734ce3a80a1965f0049","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"Troubleshooting","count":6},{"language":"default","tag":"CLI Reference","count":5},{"language":"default","tag":"Concepts","count":5},{"language":"default","tag":"Getting Started","count":3},{"language":"default","tag":"CI/CD","count":2},{"language":"default","tag":"Welcome","count":1}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"treatment","enabled":true,"payload":{"type":"string","value":"treatment"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"custom.css","content":"html.dark{--primary: 251 191 36 !important;--primary-light: 251 191 36 !important}html.dark .sd-hero-light{display:none}html:not(.dark) .sd-hero-dark{display:none}.sd-preview{border:1px solid #b45309;border-radius:10px}.sd-badges{display:flex;flex-wrap:wrap;gap:8px;align-items:center;justify-content:flex-start;margin:0 0 16px;padding:0}.sd-badges a,.sd-badges a:hover,.sd-badges a:visited{display:inline-flex;flex:0 0 auto;line-height:0;height:auto!important;max-height:24px;padding:0!important;margin:0!important;text-decoration:none!important;border-bottom:none!important;background:none!important;background-image:none!important}.sd-badges img{height:20px;width:auto;max-width:none;display:block;margin:0!important}"}]}
{"page":{"pagePath":"concepts/config-file","slug":"/concepts/config-file","pageMetadata":{"title":"zerv.toml config file: discovery and precedence","sidebarTitle":"Config file","description":"Commit your repo's version policy to zerv.toml once. Shared by version and flow; CLI flags still win.","href":"/concepts/config-file"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Commit your repo’s version policy to zerv.toml once. Shared by version and flow; CLI flags still win.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={code:`code`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,..._provideComponents(),...props.components},{CodeBlock,Heading,Note}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Note)_missingMdxReference(`Note`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`Commit your repo’s stable version policy to a `,_jsx(_components.code,{children:`zerv.toml`}),` once instead of repeating the same\nflags on every zerv invocation.`]}),`\n`,_jsx(Heading,{level:`2`,id:`discovery`,children:`Discovery`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`zerv`}),` walks up from the current directory to the nearest VCS repository root (Git’s `,_jsx(_components.code,{children:`.git`}),`\ntoday) and reads `,_jsx(_components.code,{children:`zerv.toml`}),` there, or the hidden `,_jsx(_components.code,{children:`.zerv.toml`}),` fallback. Config is\n`,_jsx(_components.strong,{children:`repo-scoped`}),`: one policy per repo, no subdirectory shadowing, so a version never depends\non which directory you run from.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`18`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light github-dark`,style:{backgroundColor:`#fff`,\"--shiki-dark-bg\":`#24292e`,color:`#24292e`,\"--shiki-dark\":`#e1e4e8`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`18`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A737D`,\"--shiki-dark\":`#6A737D`},children:`# Commit a zerv.toml at your repo root (stable fields only)`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`cat`}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:` >`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:` zerv.toml`}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:` \u003c\u003c`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`'EOF'`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`source = \"stdin\"`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`output_template = \"v{{ major }}.{{ minor }}.{{ patch }}\"`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`EOF`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A737D`,\"--shiki-dark\":`#6A737D`},children:`# zerv reads zerv.toml automatically; no flags repeated`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A737D`,\"--shiki-dark\":`#6A737D`},children:`# (stdin carries the version payload; in a git repo use source = \"git\")`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`zerv`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:` version`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A737D`,\"--shiki-dark\":`#6A737D`},children:`# → v1.2.3`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A737D`,\"--shiki-dark\":`#6A737D`},children:`# Shared-top fields shape flow too`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`zerv`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:` flow`}),_jsx(_components.span,{style:{color:`#005CC5`,\"--shiki-dark\":`#79B8FF`},children:` --schema`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:` standard`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A737D`,\"--shiki-dark\":`#6A737D`},children:`# → v1.2.3`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A737D`,\"--shiki-dark\":`#6A737D`},children:`# A CLI flag still wins over the file`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`zerv`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:` version`}),_jsx(_components.span,{style:{color:`#005CC5`,\"--shiki-dark\":`#79B8FF`},children:` --output-template`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:` \"release-{{ major }}\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A737D`,\"--shiki-dark\":`#6A737D`},children:`# → release-1`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`precedence`,children:`Precedence`}),`\n`,_jsx(_components.p,{children:`Top wins:`}),`\n`,_jsx(CodeBlock,{numberOfLines:`2`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light github-dark`,style:{backgroundColor:`#fff`,\"--shiki-dark-bg\":`#24292e`,color:`#24292e`,\"--shiki-dark\":`#e1e4e8`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`2`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`CLI flag > --config-file \u003cpath> > discovered zerv.toml > builtin default`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`--config-file \u003cpath>`}),` reads that file `,_jsx(_components.strong,{children:`instead of`}),` discovering `,_jsx(_components.code,{children:`zerv.toml`}),`; the\ndiscovered file is never read. Pass the null device to disable config entirely: the empty\nfile yields no overrides, restoring builtin behavior. There is no `,_jsx(_components.code,{children:`--no-config`}),` flag; the\nnull device is the escape hatch (`,_jsx(_components.code,{children:`/dev/null`}),` on Unix and macOS, `,_jsx(_components.code,{children:`NUL`}),` on Windows).`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`13`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light github-dark`,style:{backgroundColor:`#fff`,\"--shiki-dark-bg\":`#24292e`,color:`#24292e`,\"--shiki-dark\":`#e1e4e8`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`13`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A737D`,\"--shiki-dark\":`#6A737D`},children:`# An explicit --config-file is read instead of discovering zerv.toml`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`cat`}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:` >`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:` explicit.toml`}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:` \u003c\u003c`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`'EOF'`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`source = \"stdin\"`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`output_template = \"EXPL{{ major }}\"`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`EOF`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`zerv`}),_jsx(_components.span,{style:{color:`#005CC5`,\"--shiki-dark\":`#79B8FF`},children:` --config-file`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:` ./explicit.toml`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:` version`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A737D`,\"--shiki-dark\":`#6A737D`},children:`# → EXPL1`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A737D`,\"--shiki-dark\":`#6A737D`},children:`# The null device disables all config (the empty file yields no overrides).`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A737D`,\"--shiki-dark\":`#6A737D`},children:`# /dev/null on Unix and macOS, NUL on Windows.`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`zerv`}),_jsx(_components.span,{style:{color:`#005CC5`,\"--shiki-dark\":`#79B8FF`},children:` --config-file`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:` /dev/null`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:` version`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A737D`,\"--shiki-dark\":`#6A737D`},children:`# → 1.2.3`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`file-structure`,children:`File structure`}),`\n`,_jsxs(_components.p,{children:[`Stable fields live at the shared top (apply to both subcommands); `,_jsx(_components.code,{children:`[version]`}),` and `,_jsx(_components.code,{children:`[flow]`}),`\nsections override per-subcommand:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`13`,language:`toml`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light github-dark`,style:{backgroundColor:`#fff`,\"--shiki-dark-bg\":`#24292e`,color:`#24292e`,\"--shiki-dark\":`#e1e4e8`},language:`toml`,children:_jsxs(_components.code,{language:`toml`,numberOfLines:`13`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A737D`,\"--shiki-dark\":`#6A737D`},children:`# shared top: applies to every subcommand`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`source = `}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`\"stdin\"`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`output_format = `}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`\"semver\"`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`output_template = `}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`\"v{{ major }}.{{ minor }}.{{ patch }}\"`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`schema = `}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`\"standard-context\"`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`[`}),_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`version`}),_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`] `}),_jsx(_components.span,{style:{color:`#6A737D`,\"--shiki-dark\":`#6A737D`},children:\"# optional: override the shared schema for `version` only\"})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`schema = `}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`\"standard-no-context\"`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`[`}),_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`flow`}),_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`] `}),_jsx(_components.span,{style:{color:`#6A737D`,\"--shiki-dark\":`#6A737D`},children:`# flow-only stable policy`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`post_mode = `}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`\"tag\"`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`pre_release_label = `}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`\"beta\"`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`hash_branch_len = `}),_jsx(_components.span,{style:{color:`#005CC5`,\"--shiki-dark\":`#79B8FF`},children:`7`})]}),`\n`]})})}),`\n`,_jsx(Note,{children:_jsxs(_components.p,{children:[_jsx(_components.code,{children:`output_prefix`}),` and `,_jsx(_components.code,{children:`output_template`}),` conflict: they cannot both be set. Put the prefix\ndirectly in the template (`,_jsx(_components.code,{children:`\"v{{ major }}...\"`}),`), or use `,_jsx(_components.code,{children:`output_prefix`}),` with `,_jsx(_components.code,{children:`output_format`}),`\nand no template.`]})}),`\n`,_jsxs(_components.p,{children:[`Ephemeral per-build fields (`,_jsx(_components.code,{children:`--dirty`}),`, `,_jsx(_components.code,{children:`--bump-minor`}),`, `,_jsx(_components.code,{children:`--major`}),`, …) are `,_jsx(_components.strong,{children:`not`}),` allowed in\nthe file: a typo’d or stale key fails loud at parse (`,_jsx(_components.code,{children:`deny_unknown_fields`}),`) rather than\nshipping silently on the next CI run.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"codeStyling":{"theme":{"light":"github-light","dark":"github-dark"}},"config":{},"pageMetadata":{"title":"zerv.toml config file: discovery and precedence","sidebarTitle":"Config file","description":"Commit your repo's version policy to zerv.toml once. Shared by version and flow; CLI flags still win.","href":"/concepts/config-file"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Discovery","slug":"discovery","depth":2,"children":[]},{"title":"Precedence","slug":"precedence","depth":2,"children":[]},{"title":"File structure","slug":"file-structure","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"zerv","siteName":"zerv","title":"zerv.toml config file: discovery and precedence - zerv","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-08-25T04:13:29.663Z","gitLastModified":"2026-08-25T04:13:00.000Z","originalFileLocation":"concepts/config-file.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Commit your repo\u0026#x27;s version policy to zerv.toml once. Shared by version and flow; CLI flags still win.\">\u003cmeta data-mint-head name=\"application-name\" content=\"zerv\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/zerv/Gr3uB9R9jznvhEnB/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/zerv/Gr3uB9R9jznvhEnB/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/zerv/Gr3uB9R9jznvhEnB/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/zerv/Gr3uB9R9jznvhEnB/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/zerv/Gr3uB9R9jznvhEnB/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/zerv/Gr3uB9R9jznvhEnB/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/zerv/Gr3uB9R9jznvhEnB/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/zerv/Gr3uB9R9jznvhEnB/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/zerv/Gr3uB9R9jznvhEnB/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"zerv.toml config file: discovery and precedence - zerv\">\u003cmeta data-mint-head property=\"og:description\" content=\"Commit your repo\u0026#x27;s version policy to zerv.toml once. Shared by version and flow; CLI flags still win.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"zerv\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://zerv.wisl.dev/concepts/config-file\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://zerv.wisl.dev/img/brand/og-card-light.png\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"zerv.toml config file: discovery and precedence - zerv\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Commit your repo\u0026#x27;s version policy to zerv.toml once. Shared by version and flow; CLI flags still win.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://zerv.wisl.dev/img/brand/og-card-light.png\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/zerv/Gr3uB9R9jznvhEnB/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"zerv\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#F59E0B\">\u003clink data-mint-head rel=\"canonical\" href=\"https://zerv.wisl.dev/concepts/config-file\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/concepts/config-file.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://zerv.wisl.dev/#organization\",\"name\":\"zerv\",\"url\":\"https://zerv.wisl.dev\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/zerv/Ak0rLTc0jknhvwpO/img/brand/zerv-lockup.svg?fit=max\u0026auto=format\u0026n=Ak0rLTc0jknhvwpO\u0026q=85\u0026s=53561e784924d81ab5bceaa553c35e12\"},\"sameAs\":[\"https://github.com/wislertt/zerv\",\"https://pypi.org/project/zerv-version/\",\"https://crates.io/crates/zerv\",\"https://wisl.dev\"]},{\"@type\":\"WebSite\",\"@id\":\"https://zerv.wisl.dev#website\",\"name\":\"zerv\",\"url\":\"https://zerv.wisl.dev\",\"publisher\":{\"@id\":\"https://zerv.wisl.dev/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://zerv.wisl.dev/concepts/config-file#webpage\",\"url\":\"https://zerv.wisl.dev/concepts/config-file\",\"name\":\"zerv.toml config file: discovery and precedence\",\"description\":\"Commit your repo's version policy to zerv.toml once. Shared by version and flow; CLI flags still win.\",\"dateModified\":\"2026-08-25T04:13:00.000Z\",\"isPartOf\":{\"@id\":\"https://zerv.wisl.dev#website\"},\"breadcrumb\":{\"@id\":\"https://zerv.wisl.dev/concepts/config-file#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://zerv.wisl.dev/concepts/config-file#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Concepts\",\"item\":\"https://zerv.wisl.dev/concepts/flow\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"zerv.toml config file: discovery and precedence\",\"item\":\"https://zerv.wisl.dev/concepts/config-file\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://zerv.wisl.dev/concepts/config-file#article\",\"headline\":\"zerv.toml config file: discovery and precedence\",\"name\":\"zerv.toml config file: discovery and precedence\",\"description\":\"Commit your repo's version policy to zerv.toml once. Shared by version and flow; CLI flags still win.\",\"url\":\"https://zerv.wisl.dev/concepts/config-file\",\"mainEntityOfPage\":{\"@id\":\"https://zerv.wisl.dev/concepts/config-file#webpage\"},\"image\":\"https://zerv.wisl.dev/img/brand/og-card-light.png\",\"dateModified\":\"2026-08-25T04:13:00.000Z\",\"publisher\":{\"@id\":\"https://zerv.wisl.dev/#organization\"},\"isPartOf\":{\"@id\":\"https://zerv.wisl.dev#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"zerv\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"zerv\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/concepts/config-file.md","siteName":"zerv","nav":{"global":null,"groups":[{"group":"Welcome","pages":[{"title":"Dynamic versioning from git for every commit","sidebarTitle":"zerv","href":"/index"}]},{"group":"Getting Started","pages":[{"title":"Install zerv from PyPI, crates.io, or binaries","sidebarTitle":"Installation","href":"/getting-started/installation"},{"title":"zerv quickstart: your first version from git","sidebarTitle":"Quickstart","href":"/getting-started/quickstart"},{"title":"Why zerv","href":"/getting-started/why-zerv"}]},{"group":"Concepts","pages":[{"title":"zerv flow: branch-based versioning automation","sidebarTitle":"Flow","href":"/concepts/flow"},{"title":"zerv version: manual versioning pipeline","sidebarTitle":"Version","href":"/concepts/version"},{"title":"Version schema system and 22 presets","sidebarTitle":"Schema system","href":"/concepts/schema-system"},{"title":"Version formats and Tera templates","sidebarTitle":"Formats and templates","description":"Output formats (SemVer, PEP440, ZERV RON), the ZERV_RON piping pattern, and the Tera template system with all variables and functions.","href":"/concepts/formats-and-templates"},{"title":"zerv.toml config file: discovery and precedence","sidebarTitle":"Config file","href":"/concepts/config-file"}]},{"group":"CI/CD","pages":[{"title":"Version every GitHub Actions build","sidebarTitle":"GitHub Actions","description":"Version every CI build with the reusable zerv-versioning workflow. One call, every format as outputs.","href":"/cicd/github-actions"},{"title":"Coexisting with semantic-release","href":"/cicd/semantic-release"}]},{"group":"CLI Reference","pages":[{"title":"zerv CLI commands and global flags","sidebarTitle":"zerv","href":"/cli/zerv"},{"title":"zerv version","href":"/cli/version"},{"title":"zerv flow","href":"/cli/flow"},{"title":"zerv check","href":"/cli/check"},{"title":"zerv render","href":"/cli/render"}]},{"group":"Troubleshooting","pages":[{"title":"zerv errors and troubleshooting","sidebarTitle":"Troubleshooting","href":"/troubleshooting/index"},{"title":"No version tags are reachable from HEAD","sidebarTitle":"No reachable tags","href":"/troubleshooting/no-version-tags-reachable"},{"title":"VCS not found: Not in a git repository","sidebarTitle":"VCS not found","href":"/troubleshooting/vcs-not-found"},{"title":"Unknown schema","sidebarTitle":"Unknown schema","href":"/troubleshooting/unknown-schema"},{"title":"Conflicting options","sidebarTitle":"Conflicting options","href":"/troubleshooting/conflicting-options"},{"title":"Config parse error","sidebarTitle":"Config parse error","href":"/troubleshooting/config-parse-error"}]}]},"basePath":"","title":"zerv.toml config file: discovery and precedence - zerv","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":[],"chunks":[]}