Installation¶
Quick start¶
$ cd my-project
$ uvx -- repomatic init
$ git add .
$ git commit -m "Update repomatic files"
$ git push
Works for both new and existing repositories. Run repomatic init --help to see available components and options: the workflows then take it from there, opening issues and PRs to guide any remaining setup.
Try it now¶
Thanks to uv, you can run it in one command, without installation or venv:
$ uvx -- repomatic --help
$ repomatic --help
Usage: repomatic [OPTIONS] COMMAND [ARGS]...
Options:
--jobs [auto|max|INTEGER] Number of parallel jobs. Accepts an integer, auto
(the host's logical CPUs, minus one when there
are three or more) or max (all logical CPUs).
--jobs 0 runs sequentially. [default: auto]
-h, --help Show this message and exit.
Configuration options:
--config LOCATION Location of the configuration file. Supports
local path with glob patterns or remote URL.
[default: ~/.config/repomatic/]
--no-config Ignore all configuration files and only use
command line parameters and environment
variables.
--validate-config LOCATION Validate the configuration file and exit.
--export-config FORMAT Export the configuration in the selected format
to <stdout>, then exit.
Output options:
--accessible Accessibility mode: disable colors and render
tables in a borderless, screen-reader-friendly
format.
--color [auto|always|never] Colorize the output. A bare --color is the same
as --color=always. [default: auto]
--no-color Disable colorization (alias of --color=never).
--progress / --no-progress Show progress indicators during long operations.
Disabled for non-interactive output (pipes, dumb
terminals, CI) and by --accessible. [default:
progress]
--theme [auto|dark|dracula|light|manpage|monokai|nord|solarized-dark]
Color theme used for help screens. [default:
dark]
--table-format FORMAT Rendering style of tables. [default: rounded-
outline]
Logging options:
--verbosity LEVEL Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
[default: WARNING]
-v, --verbose Increase the default WARNING verbosity by one
level for each additional repetition of the
option. [default: 0]
-q, --quiet Decrease the default WARNING verbosity by one
level for each additional repetition of the
option. [default: 0]
--debug Shorthand for --verbosity DEBUG.
Introspection options:
--time / --no-time Measure and print elapsed execution time.
[default: no-time]
--params Show all CLI parameters, their provenance,
defaults and value, then exit.
--tree Show the tree of nested subcommands and exit.
--man Read the command's manual page and exit.
--help-format [carapace|json|json-full|man|markdown|markdown-full]
Render the command in the given format and exit.
--version Show the version and exit.
Linting & checks:
audit Report (and optionally fix) vulnerable dependencies
cloudflare-pages Create, check or update the Cloudflare Pages project
cloudflare-r2 Serve site files over the Pages size limit from
Cloudflare R2
fix-awesome-toc Remove the table-of-contents entries awesome-lint
rejects
lint-changelog Check changelog dates against release dates
lint-deps Check dependencies resolve from the public index
lint-repo Check repository files against repomatic conventions
lint-workflows Lint downstream workflow caller files
GitHub issues & PRs:
apply-labels Label an issue or PR from its content and changed files
broken-links Manage broken links issue lifecycle
lock-threads Lock closed, inactive issues and PRs
pr-body Generate PR body with workflow metadata
pr-sync Create, refresh or retire an automation PR
setup-guide Manage setup guide issue lifecycle
sponsor-label Label issues/PRs from GitHub sponsors
unsubscribe-threads Unsubscribe from closed, inactive notification threads
CI & runners:
cancel-runs Cancel in-progress workflow runs for a branch
ci-status Report which CI jobs are red, and which of them gate a
merge
job-timings Measure how long each runner image takes, from finished
runs
sync-runner-images Move runner images forward as GitHub retires and
supersedes them
Release & versioning:
changelog Maintain a Markdown-formatted changelog
close-stale-bump-pr Close a stale version-bump PR
git-commit-push Commit files and push, rebasing on rejection
git-tag Create and push a Git tag
pack-attestation Name an attestation bundle after the asset it attests
pack-binaries Pack compiled binaries and their versionless aliases
pack-plugin Pack the skills and agents as a Claude Code plugin
prepare-release Freeze version, changelog and pins for a release
scan-virustotal Upload release binaries to VirusTotal
sync-binaries Regenerate the binaries catalog page
verify-binary Verify binary architecture and OS floor
Forge sampling:
sample-metrics Record what forges say about the repositories this
project tracks
Project setup:
format-images Format images with lossless optimization
init Bootstrap a repository to use reusable workflows
list-skills List available Claude Code skills
show-config Print [tool.repomatic] configuration reference
show-metadata Print repository and CI state as key/value pairs for
workflows
show-test-matrix Render the CI test matrix as a grid
update-checksums Recompute SHA-256 checksums for the binary tool registry
update-dep-graph Generate dependency graph from uv lockfile
update-docs Regenerate Sphinx API docs and dynamic content
Sync:
sync-action-pins Bump SHA-pinned GitHub Actions to their latest release
sync-bumpversion Sync bumpversion config from bundled template
sync-dep-sources Swap git-tracked dependencies to their released versions
sync-deps Update dependencies, all or a named subset
sync-dev-release Sync rolling dev pre-release on GitHub
sync-github-releases Sync GitHub release notes from changelog
sync-gitignore Sync .gitignore from gitignore.io templates
sync-labels Sync repository labels via labelmaker
sync-mailmap Sync Git's .mailmap file with missing contributors
sync-tool-versions Bump registry tool versions from upstream releases
sync-uv-lock Re-lock dependencies and roll cooldown overrides forward
sync-workflow-pins Bump npm/PyPI version literals in workflow YAML
Other commands:
cache Manage the download cache
help Show help for a command.
run Run a registered external tool, pinned and checksum-
verified
$ uvx -- repomatic==7.17.1 --help
$ uvx --from "repomatic @ git+https://github.com/kdeldycke/repomatic" -- repomatic --help
Installation methods¶
repomatic is available on a couple of package managers:
Easiest way is to install uv, then install repomatic system-wide with the uv tool command:
$ uv tool install repomatic
You can install the latest stable release and its dependencies with a simple pip call:
$ python -m pip install repomatic
If you have difficulties to use pip, see pip’s own installation instructions.
pipx is a great way to install Python applications globally:
$ pipx install repomatic
A repomatic package is available on AUR and can be installed with any AUR helper:
$ yay -S python-repomatic
$ paru -S python-repomatic
$ pacaur -S python-repomatic
Python compatibility¶
The table below shows which Python versions each repomatic release range supports, derived from the declarations in each git tag’s pyproject.toml. It is refreshed by click-extra’s {matrix} directive machinery through the update-docs job. A ✅ marks a version the release declares through its classifiers. A ❌ marks one its requires-python rules out. A – marks one the release neither declared nor excluded, which is what an open-ended requires-python leaves for a Python published after that tag. Releases prior to 4.0.0 did not declare Python version support in any form and are not represented.
|
|
|
|
|
|
|
|
|
|---|---|---|---|---|---|---|---|---|
|
✅ |
✅ |
✅ |
✅ |
✅ |
✅ |
❌ |
❌ |
|
– |
✅ |
✅ |
✅ |
✅ |
✅ |
❌ |
❌ |
|
– |
✅ |
✅ |
✅ |
✅ |
❌ |
❌ |
❌ |
|
– |
– |
✅ |
✅ |
✅ |
❌ |
❌ |
❌ |
|
– |
– |
✅ |
✅ |
✅ |
✅ |
❌ |
❌ |
|
– |
– |
– |
✅ |
✅ |
✅ |
✅ |
❌ |
|
– |
– |
– |
✅ |
✅ |
✅ |
✅ |
✅ |
Binaries¶
To ease deployment, standalone executables of repomatic’s latest version are available as direct downloads for several platforms and architectures:
Platform |
|
|
|---|---|---|
Linux |
||
macOS |
||
Windows |
That way you have a chance to try it out without installing Python or uv. Or embed it in your CI/CD pipelines running on minimal images. Or run it on old platforms without worrying about dependency hell.
Binaries of all past releases, with their VirusTotal analyses, are cataloged on the binaries page.
Release verification¶
Every binary is signed with a build provenance attestation at release time. After downloading one, verify it with the gh CLI:
$ gh attestation verify repomatic-7.17.1-linux-x64.bin --repo kdeldycke/repomatic --signer-repo kdeldycke/repomatic
--signer-repo kdeldycke/repomatic is required because the release runs from the reusable _release-engine.yaml workflow whose signing identity is kdeldycke/repomatic. Downstream projects that build binaries through the same reusable workflow verify with their own --repo but keep --signer-repo kdeldycke/repomatic.
The PyPI distributions carry their own PEP 740 attestations, visible and verifiable on the PyPI project page.
Man pages¶
repomatic exposes a --man option on its root command, which typesets the manual and pages it, the way man does:
$ repomatic --man
To get the roff source instead, ask for the man rendering of --help-format:
$ repomatic --help-format man
The full command tree is also pre-rendered as static .1 files:
Bundled as
repomatic-manpages.tar.gzon every GitHub release. Download, extract, and copy to${MANPATH%%:*}/man1/(typically/usr/local/share/man/man1/).Rendered as browser-viewable HTML siblings under https://repomatic.net/man/, which indexes the whole set.
Downstream packagers can regenerate them from source as part of their build phase:
$ click-extra wrap --help-format man --output-dir /usr/share/man/man1/ repomatic.cli.main:repomatic
The generator honors SOURCE_DATE_EPOCH for reproducible builds. See the click-extra man-page reference for other invocation forms (uvx for build sandboxes, .py file paths, and the programmatic API).