Skip to main content

repoman

Declarative multi-forge Git workspace sync — preview-first CLI that plans and applies local clones (and later forge-side mirrors) from one YAML file. Works on Linux, macOS, and Windows.

Status Meaning
OK No action needed
WOULD UPDATE Preview of a planned change
UPDATED Change applied
SKIP Left unchanged (e.g. dirty tree, non–fast-forward)
WARN Informational issue
ERROR Failure

Documentation

Resource Description
Getting started Install, first config, tokens, first sync (start here)
Published docs MkDocs site (after GitHub Pages is enabled — see Deployment)
Full docs site MkDocs index — build with uv run mkdocs serve
Design spec Architecture, schema, roadmap
Examples Runnable sample commands and namespace include / exclude recipes
Examples (repo) Safe runnable YAML under examples/

Requirements

  • Python ≥ 3.11
  • Git on PATH
  • uv — environments and CI

Install

pipx install repoman-cli
# or: pip install repoman-cli
# or: uv pip install repoman-cli
repoman --version

The PyPI package name is repoman-cli; the CLI command is still repoman.

From a clone (development)

git clone <this-repo-url> repoman && cd repoman
uv sync --all-groups
uv run repoman --version

Optional: install the CLI into the active environment from the checkout:

uv pip install .
repoman --version

First-time setup (5 minutes)

1. Create configuration

repoman config init
repoman config path    # shows where repoman.yaml was created
Platform Default config directory
Linux / macOS ~/.config/repoman/
Windows %USERPROFILE%\.repoman\

Set REPOMAN_HOME to use a different directory on any OS, or pass --config PATH per command.

2. Edit repoman.yaml

Set paths.workspace_root, configure remotes, and add at least one namespaces entry (or explicit repos). See getting started for a GitHub namespace example and token setup.

3. Tokens

Use environment variables (token_env in YAML) or credentials.toml beside repoman.yaml with token_credentials — never put tokens in YAML. Details: Getting started § Tokens.

4. Validate, preview, apply

repoman config validate
repoman doctor
repoman local plan                  # preview only
repoman local status                # read-only; add --json for automation
repoman local sync --write          # clones / fetch / ff-only merges

Adjust settings without an editor:

repoman config set paths.workspace_root '~/repositories' --write

Safety: local sync without --write never mutates clones; dirty trees and non–fast-forward states produce SKIP, not silent data loss.

What's implemented

  • config — init, path, validate, show, set
  • doctor — tokens and optional API reachability
  • local plan / local sync / local status — discovery, layout, guarded git operations

Not yet shipped: mirrors — see roadmap.

Development

uv sync --all-groups
uv run ruff check .
uv run ruff format --check .
uv run pytest
uv run mkdocs build --strict
uv run mkdocs serve    # local docs at http://127.0.0.1:8000

Contributor rules: AGENTS.md (backlog in .adr.md, chatlogs under docs/chatlogs/).

License

Released under the MIT License — see LICENSE.

Metadata

Release files for repoman-cli 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for repoman-cli 0.5.0
File Size Uploaded Provenance Actions
repoman_cli-0.5.0.tar.gz 141.2 kB With provenance Details for repoman_cli-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for repoman-cli 0.5.0
File Interpreter ABI Platform Actions
repoman_cli-0.5.0-py3-none-any.whl Python 3 none any Details for repoman_cli-0.5.0-py3-none-any.whl

Total release size: 179.1 kB

Release files / repoman_cli-0.5.0.tar.gz

Download URL repoman_cli-0.5.0.tar.gz
Size 141.2 kB
Tags Source
SHA-256 checksum
How to use checksums
c313606018c59e98f7ecaa7ee206100f6098da53339385dcd78827ae6791d263
BLAKE2b-256 checksum
How to use checksums
4ddbc2bfb214595ef8f0cca39dd3de013b4d2de6e7ec1e8b07fc1d9e887661e1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Sep 5, 2026.

Transparency log

Release files / repoman_cli-0.5.0-py3-none-any.whl

Download URL repoman_cli-0.5.0-py3-none-any.whl
Size 37.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1807df130d542fc3457d775902b0f61252389cbd98c38493cbd454a238b98c8a
BLAKE2b-256 checksum
How to use checksums
88f5cfbd117377eb0f3a4a63de0031ba3cbfae7d46806bd71885bc6ffd666eb9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Sep 5, 2026.

Transparency log

Security for repoman-cli 0.5.0

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.

Select from 2 files

Attestation for repoman_cli-0.5.0.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 Sep 5, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page