gestate
Set a minimum release age on local package managers so installs ignore versions younger than N days. Most malicious packages are caught and yanked within days of publishing; refusing fresh versions blocks the bulk of supply-chain attacks.
Run
uvx gestate # interactive
uvx gestate set 3 # 3-day minimum, installed tools only
uvx gestate set 3 --all # also pre-configure file-based tools (bun, deno, uv)
uvx gestate set 3 --local # write per-project config files in the current repo
uvx gestate revert # remove gestate's settings
uvx gestate revert --local # remove the per-project gate from this repo
uvx gestate explain bun # show how one tool's setting is stored
uvx gestate trust my-pkg --python # exempt a package from the age delay
uvx gestate trust --rm my-pkg # remove an exemption
uvx gestate trust # list trusted packages
Interactive mode always shows a plan and asks for explicit confirmation before touching anything. The subcommands skip the confirm — meant for scripts, not your daily shell. Running with no subcommand outside a TTY exits with an error.
Plain text output is used when stdout isn't a terminal (no Rich tables/colors).
What it sets
| Tool | Where | Key (unit) |
|---|---|---|
| npm | ~/.npmrc |
min-release-age (days) |
| pnpm | global pnpm config | minimumReleaseAge (minutes) |
| yarn | ~/.yarnrc.yml (4.10+) |
npmMinimalAgeGate (minutes) |
| bun | ~/.bunfig.toml |
[install] minimumReleaseAge (seconds) |
| deno | shell profile | alias deno='command deno --minimum-dependency-age=P<N>D' |
| pip | user pip config | global.uploaded-prior-to (P<N>D) |
| uv | ~/.config/uv/uv.toml |
exclude-newer ("N days"), plus a git filter for uv.lock |
gestate explain <tool> prints that tool's current value and the exact mechanism set / revert use.
Scope:
- default — only configure installed tools
--all— also pre-write config files forbun,deno,uveven if they aren't installed yet
Project-local policy (--local)
gestate set <days> --local writes each tool's native, committed-to-the-repo config so the gate travels with the project and applies to anyone who clones it — even collaborators who never ran gestate. It only configures tools the repo gives evidence of (a lockfile, manifest, or existing tool config in the current directory), so it won't litter a JS repo with uv.toml or vice versa.
| Tool | Project file (cwd) | Key (unit) |
|---|---|---|
| npm | .npmrc |
min-release-age (days) |
| pnpm | pnpm-workspace.yaml |
minimumReleaseAge (minutes) |
| yarn | .yarnrc.yml |
npmMinimalAgeGate (minutes) |
| bun | bunfig.toml |
[install] minimumReleaseAge (seconds) |
| deno | deno.json |
minimumDependencyAge (P<N>D) |
| uv | uv.toml |
exclude-newer ("N days") |
pip has no per-project config (and no dependency-age gate), so it's skipped. If a deno.json has comments (JSONC), gestate won't rewrite it — it prints the line to add yourself. revert --local removes the key and deletes any file it leaves empty.
Revert
uvx gestate revert removes everything gestate set:
- CLI tools —
config delete/config unset bun/uv— remove the key; delete the file if it was the only keydeno— remove our alias line; leave foreignalias deno=lines alone
Backups (.bak) are written next to any edited shell-profile or TOML file.
Per-package exemptions (trust)
gestate trust lets you exempt specific packages from the age delay so they always get the latest version:
gestate trust @myorg/* # auto-detects Node (scoped package)
gestate trust my-lib --python # exempt in uv
gestate trust --rm my-lib --python # remove exemption
gestate trust # list all trusted packages
gestate trust --python # list Python ecosystem only
The --python / --node flags are optional — gestate auto-detects the ecosystem from scoped packages (@scope/name → Node) or the current directory (pyproject.toml → Python, package.json → Node). When it can't tell, it asks you to specify.
Supported tools: bun, uv, yarn, pnpm, npm (requires npm ≥ 11.17.0). deno and pip don't support per-package allowlists and print a warning. For manual config details, see docs/allowlists.md.
Caveats
- yarn: 4.10+ only. Older yarn is detected and skipped.
- deno: no global config exists; the shell alias only covers interactive shells. For CI, pass
--minimum-dependency-age=P<N>Dtodeno install/deno update, or commit a projectdeno.jsonwith"minimumDependencyAge": "P<N>D". - npm trust: requires npm ≥ 11.17.0. gestate skips npm with a note when the installed npm is older (global scope only — a project
.npmrcis still written, since it's enforced by whoever installs). Early npm releases didn't honormin-release-age-excludeinnpxor every reify path. - pip exclude: none —
global.uploaded-prior-tois global only. - uv lockfiles: see Keeping uv.lock stable.
- uv config location: with
UV_CONFIG_FILEset, uv reads only that file (not~/.config/uv/uv.toml, nor the project's[tool.uv]), so gestate writes there instead. WithUV_NO_CONFIGset, uv reads no config at all andsetwarns that the gate has no effect.
Keeping uv.lock stable
uv writes the exclude-newer settings in effect into uv.lock's [options], including the ones from your global uv.toml (astral-sh/uv#18775). Collaborators without that config strip them again, so the lock flip-flops between you, and a lock committed with them can trip uv sync --locked in CI or a Docker build.
So when it configures uv, gestate set also adds a global git clean filter:
filter.gestate-uv.clean = gestate uv-lock-clean %fin your global git config (uvx gestate …ifgestateisn't on yourPATH)uv.lock filter=gestate-uvin your global attributes file (core.attributesFile, else~/.config/git/attributes)
Git then sees each uv.lock without the entries that came only from your global config, while uv keeps them in your working copy. Anything the project sets itself (uv.toml, or [tool.uv] in pyproject.toml, next to the lock) is left alone, as is every other option. A UV_EXCLUDE_NEWER in the environment counts as the project's too, since gestate set clears it from your shell profile and what's left is per-project (direnv, CI). gestate revert removes the filter.
Things to know:
- A repo whose committed
uv.lockalready contains your global settings shows the lock as modified; commit it to drop them. - After a pull changes
uv.lockand uv rewrites it,git statuscan list it as modified with an emptygit diff: git sees the size change before it runs the filter.git add uv.lockclears it and stages nothing. - If gestate can't run, git uses the file unfiltered, so the worst case is the old churn.
- Committing the setting with
gestate set N --localis the other fix: everyone, CI included, then resolves the same way.
For PR-creation guards (Dependabot, Renovate) and adjacent layers, see docs/complementary.md.
Development
uv sync
uv run pytest
Requires Python 3.11+, macOS or Linux.
Metadata
Release files for gestate 1.3.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gestate-1.3.2.tar.gz | 55.4 kB | With provenance | Details for gestate-1.3.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gestate-1.3.2-py3-none-any.whl | Python 3 | none | any | Details for gestate-1.3.2-py3-none-any.whl |
Total release size: 82.0 kB
Release files / gestate-1.3.2.tar.gz
| Download URL | gestate-1.3.2.tar.gz |
|---|---|
| Size | 55.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e635804d4933764097386bc5590b5f9e560768199057fb6dd25887be3e6345d8
|
|
BLAKE2b-256 checksum How to use checksums |
4ad5432a937bcc17ab344692abe03f69045c0d8cb2b015c5cecaa99d318a6ed3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.
Transparency logRelease files / gestate-1.3.2-py3-none-any.whl
| Download URL | gestate-1.3.2-py3-none-any.whl |
|---|---|
| Size | 26.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
14383da3e297bd71336c114ee9c191c8265351171e0beded9d86cfb65ac57b9b
|
|
BLAKE2b-256 checksum How to use checksums |
b858699558cad9cc274d6cf48e44f99afe78148d24445ed2c5b0103f925fa432
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.
Transparency logSecurity for gestate 1.3.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for gestate-1.3.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.