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¶
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:
--time / --no-time Measure and print elapsed execution time.
[default: no-time]
--config CONFIG_PATH Location of the configuration file. Supports
local path with glob patterns or remote URL.
[default: ~/.config/repomatic/{*.toml,*.yaml,*.ym
l,*.json,*.ini,pyproject.toml}]
--no-config Ignore all configuration files and only use
command line parameters and environment
variables.
--validate-config FILE Validate the configuration file and exit.
--export-config FORMAT Export the configuration in the selected format
to <stdout>, then exit.
--accessible Accessibility mode: disable colors and render
tables in a plain, 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 [dark|dracula|light|manpage|monokai|nord|solarized_dark]
Color theme used for help screens. [default:
dark]
--params Show all CLI parameters, their provenance,
defaults and value, then exit.
--table-format [aligned|asciidoc|colon-grid|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|hjson|html|jira|json|json5|jsonc|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|toml|tsv|unsafehtml|vertical|xml|yaml|youtrack]
Rendering style of tables. [default: rounded-
outline]
--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]
--tree Show the tree of nested subcommands and exit.
--man Show the command's man page (roff) and exit.
--version Show the version and exit.
--jobs [auto|max|INTEGER] Number of parallel jobs. Accepts an integer,
'auto' (one fewer than the host's logical CPUs)
or 'max' (all logical CPUs). 0 runs sequentially.
[default: auto]
-h, --help Show this message and exit.
Project setup:
init Bootstrap a repository to use reusable workflows
metadata Output project metadata
show-config Print [tool.repomatic] configuration reference
show-test-matrix Render the CI test matrix as a grid
workflow Lint downstream workflow caller files
update-dep-graph Generate dependency graph from uv lockfile
update-docs Regenerate Sphinx API docs and dynamic content
list-skills List available Claude Code skills
update-checksums Recompute SHA-256 checksums for the binary tool
registry
format-images Format images with lossless optimization
Release & versioning:
changelog Maintain a Markdown-formatted changelog
prepare-release Prepare files for a release
check-version Check if a version bump is allowed
close-stale-bump-pr Close a stale version-bump PR
git-tag Create and push a Git tag
git-commit-push Commit files and push, rebasing on rejection
scan-virustotal Upload release binaries to VirusTotal
sync-binaries Regenerate the binaries catalog page
Sync:
sync-gitignore Sync .gitignore from gitignore.io templates
sync-github-releases Sync GitHub release notes from changelog
sync-dev-release Sync rolling dev pre-release on GitHub
sync-mailmap Sync Git's .mailmap file with missing contributors
sync-dep-sources Swap git-tracked dependencies to their released
versions
sync-uv-lock Re-lock dependencies and roll cooldown overrides
forward
sync-tool-versions Bump registry tool versions from upstream releases
sync-action-pins Bump SHA-pinned GitHub Actions to their latest
release
sync-workflow-pins Bump npm/PyPI version literals in workflow YAML
sync-deps Update dependencies, all or a named subset
sync-bumpversion Sync bumpversion config from bundled template
clean-unmodified-configs Remove config files that match bundled defaults
sync-labels Sync repository labels via labelmaker
GitHub issues & PRs:
sponsor-label Label issues/PRs from GitHub sponsors
broken-links Manage broken links issue lifecycle
setup-guide Manage setup guide issue lifecycle
unsubscribe-threads Unsubscribe from closed, inactive notification
threads
cancel-runs Cancel in-progress workflow runs for a branch
pr-body Generate PR body with workflow metadata
Linting & checks:
verify-binary Verify binary architecture and OS floor
audit Report (and optionally fix) vulnerable dependencies
lint-repo Run repository consistency checks
lint-changelog Check changelog dates against release dates
run Run an external tool with managed config
cache Manage the download cache
Other commands:
help Show help for a command.
$ uvx -- repomatic==7.4.1 --help
$ uvx --from "repomatic @ git+https://github.com/kdeldycke/repomatic" -- repomatic --help
Install 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. Releases prior to 4.0.0 did not declare Python version support in any form and are not represented.
|
Released |
|
|
|
|
|
|
|
|---|---|---|---|---|---|---|---|---|
|
2025-12-05 |
✅ |
✅ |
✅ |
✅ |
✅ |
❌ |
❌ |
|
2025-10-10 |
✅ |
✅ |
✅ |
✅ |
❌ |
❌ |
❌ |
|
2025-03-05 |
❌ |
✅ |
✅ |
✅ |
❌ |
❌ |
❌ |
|
2024-11-03 |
❌ |
✅ |
✅ |
✅ |
✅ |
❌ |
❌ |
|
2024-07-27 |
❌ |
❌ |
✅ |
✅ |
✅ |
✅ |
❌ |
|
2024-06-29 |
❌ |
❌ |
✅ |
✅ |
✅ |
✅ |
✅ |
Executables¶
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.4.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.