Skip to main content

A set of utilities to maintain Gentoo overlay

Project description


PyPI version

Provides certain tools to be run on the overlay directory. See individual commands help for details.

This is a small collection of tools to help automate some tasks related to Gentoo overlay maintenance.

It can:

  • Generate a README like this.
  • Look up a package in remotes and tell if a new version is available.
  • Look up a package on and show the newest known versions.

Getting started


Install the project from PyPI:

$ pip install --user overlay-maintain-tools

Or from nitratesky overlay:

$ eselect repository enable nitratesky && emerge -a1 app-portage/overlay-maintain-tools

Sample usage

The overlay directory is at /srv/overlay. To generate a README with the badges, create a skeleton template (like the one in repo) and run:

$ overlay_maintain_tools --overlay-dir /srv/overlay mkreadme --skeleton-file /path/to/readme.template

To generate a report on packages versions in overlay, make sure that metadata.xml file has remotes set and run:

$ overlay_maintain_tools --overlay-dir /srv/overlay check-remote-versions

To look up versions in repology, create a file with mapping between package atoms and project names in repology and specify it when running the script:

$ cat /srv/overlay/repology_cache
net-news/newsboat newsboat
$ overlay_maintain_tools --overlay-dir /srv/overlay check-repology --repology-cache-location /srv/overlay/repology_cache



$ overlay_maintain_tools [OPTIONS] COMMAND [ARGS]...

General Options:

  • --version: Show version and exit.
  • --overlay-dir PATH: Specify location for overlay. [default: .]
  • --worker-count INTEGER RANGE: Number of workers for creating package cache. [default: 8]
  • --quiet: Suppresses output. For commands checking versions exit code 100 means newer versions are available. [default: False]
  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

These options can be specified for any COMMAND except for create-config which ignores these options.


  • check-remote-versions: Prints report on the versions of packages.
  • check-repology: Returns versions known to repology.
  • mkreadme: Creates a README for an overlay.


overlay_maintain_tools mkreadme

Creates a README for an overlay. The generated README can utilize data on packages available in the overlay and their versions. For sample template, see the documentation.


$ overlay_maintain_tools mkreadme [OPTIONS]


  • --skeleton-file PATH: The file containing README template. Should be inside the template directory.
  • --template-dir DIRECTORY: Template directory. Can be specified if more complex jinja2 templates will be used.
  • --output PATH: Where to save the resulting README. If not supplied - print to stdout.
  • --help: Show this message and exit.

overlay_maintain_tools check-remote-versions

Prints report on the versions of packages. Checks versions available upstream. Pulls the data from remotes specified inside tag in metadata.xml


$ overlay_maintain_tools check-remote-versions [OPTIONS]


  • --show-updates-only: Shows only packages that have updates with links to remotes_with_new_versions.
  • --background: Suppress output of this subcommand completely. Exit code = 100 denotes that there are updates in remotes
  • --color: Enable/disable color in output
  • --help: Show this message and exit.

overlay_maintain_tools check-repology

Returns versions known to repology. Reported versions will be newer than ones in overlay.


$ overlay_maintain_tools check-repology [OPTIONS]


  • --repology-cache-location PATH: Path to file with the mappings between overlay package and repology project
  • --help: Show this message and exit.

Contrib directory

There are shell completions for bash and zsh (generated through typer).

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

overlay_maintain_tools-1.3.1.tar.gz (24.7 kB view hashes)

Uploaded Source

Built Distribution

overlay_maintain_tools-1.3.1-py3-none-any.whl (27.4 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page