repomatic.init.run module

Run repomatic init: select the components, then write their files.

Selectors use the same component[/file] syntax as the exclude config option in [tool.repomatic]. Qualified entries like skills/repomatic-topics select a single file within a component.

repomatic.init.run.AWESOME_TEMPLATE_REWRITTEN_SUFFIXES = frozenset({'.md', '.yaml', '.yml'})

Extensions of the awesome-template files whose URLs name the repository.

repomatic.init.run.AWESOME_TEMPLATE_SLUG = 'kdeldycke/awesome-template'

Source slug embedded in bundled awesome-template files, rewritten at sync time.

repomatic.init.run.AWESOME_TEMPLATE_URL_RE = re.compile('/kdeldycke/awesome\\-template(?![\\w.-])')

A URL path naming the template repository itself.

The lookahead stops a longer repository name, like awesome-template-v2, from matching. Whatever else follows the slug matches: a /blob/ path, a #readme fragment, or the end of the link.

repomatic.init.run.TEMPLATE_TREE_SKIPPED = frozenset({'__init__.py', '__pycache__'})

Entries of a bundled tree that make it a package, not part of the template.

class repomatic.init.run.ReportSection(*values)

Bases: Enum

A section of the init report that lists files a run may delete.

The value is the name of the InitResult field holding the paths.

EXCLUDED = 'excluded_existing'

Files the configuration excludes, still on disk.

UNMODIFIED = 'unmodified_configs'

Tool configs identical to the bundled defaults.

REMOVED = 'removed_prunable'

Untouched orphans of assets repomatic no longer ships.

REMOVED_MODIFIED = 'removed_review'

Orphans of dropped assets, edited since repomatic shipped them.

property prunes_parents: bool

Whether deleting a path also removes the parents it leaves empty.

On for the sections whose targets sit in directories repomatic itself created (.claude/skills/<name>/). Off for unmodified tool configs, which share .github/ and the repository root with files repomatic does not own.

class repomatic.init.run.DeletionPolicy(delete_excluded=False, delete_unmodified=False, keep_removed=False, delete_removed_modified=False)

Bases: object

Which ReportSection an init run deletes from disk.

Each field is named after the init option that sets it, which is what flags() reads back to hand the same policy to a child init.

delete_excluded: bool = False

Delete the files the configuration excludes.

delete_unmodified: bool = False

Delete the tool configs identical to the bundled defaults.

keep_removed: bool = False

Keep the untouched orphans of dropped assets, deleted by default.

delete_removed_modified: bool = False

Also delete the orphans edited since repomatic shipped them.

deletes(section)

Whether this policy deletes the paths listed in section.

Return type:

bool

flags()

The init options that set this policy, for a child init.

Return type:

list[str]

class repomatic.init.run.InitResult(created=<factory>, updated=<factory>, skipped=<factory>, excluded=<factory>, excluded_existing=<factory>, unmodified_configs=<factory>, removed_prunable=<factory>, removed_review=<factory>, warnings=<factory>, previous_pin=None, adopted_pin=None)

Bases: object

Result of a repository initialization run.

created: list[str]

Relative paths of newly created files.

updated: list[str]

Relative paths of existing files overwritten with new content.

skipped: list[str]

Relative paths of skipped (already existing) files.

excluded: list[str]

Exclude entries that were applied.

excluded_existing: list[str]

Relative paths of excluded files that still exist on disk.

unmodified_configs: list[str]

Relative paths of config files identical to bundled defaults.

removed_prunable: list[tuple[str, str]]

(relative_path, successor) for on-disk orphans of dropped assets whose content matches the last-shipped version (safe to auto-delete).

removed_review: list[tuple[str, str]]

(relative_path, successor) for on-disk orphans of dropped assets that differ from the last-shipped version (locally modified: reported for manual review, never auto-deleted).

warnings: list[str]

Warning messages emitted during initialization.

previous_pin: str | None = None

Bare version of the highest upstream uses: pin the repository carried before the run, read only when a workflow component was selected. None for a first adoption, or for a run generating no workflow.

adopted_pin: str | None = None

Bare version the run wrote its thin callers at, or None when the workflow sync was skipped.

record(path, *, existed, verb='')

File a written path as created or updated, and log it.

Parameters:

• path (str) – The repository-relative path of the file written.

• existed (bool) – Whether the file was on disk before the write.

• verb (str) – Overrides the log line’s leading word (Synced header).

Return type:

None

warn(message)

Log message and keep it for the closing summary of the run.

Return type:

None

entries(section)

The entries section lists: paths, or (path, successor) pairs.

Return type:

list[str] | list[tuple[str, str]]

paths(section)

The repository-relative paths section lists.

Return type:

list[str]

prune(output_dir, policy)

Delete every section of the report policy asks to delete.

Parameters:

• output_dir (Path) – Repository root the paths are relative to.

• policy (DeletionPolicy) – The sections to delete.

Return type:

None

upgraded_pin()

(previous, adopted) when the run moved the upstream pin forward.

The pair init’s closing hint and the upgrade review are keyed on. A first adoption has no previous release to review against, a regeneration at the pinned version moves nothing, and a rollback is a deliberate step back no upgrade review should chase, so all three answer None.

Return type:

tuple[str, str] | None

next_steps(output_dir, config)

The steps left to the maintainer after the run, in order.

A run that only staged ephemeral files (init labels) produced scratch input for the command about to read it, so it has nothing to commit and no step at all.

Parameters:

• output_dir (Path) – Root of the target repository.

• config (Config) – The resolved configuration, for the skills location.

Return type:

list[str]

Returns:

One text per step. A step spanning several lines indents its commands by two spaces against its prose.

repomatic.init.run.run_init(output_dir, components=(), *, config, version=None, cooldown=True, repo='kdeldycke/repomatic', repo_slug=None)

Bootstrap a repository for use with kdeldycke/repomatic.

Creates thin-caller workflow files, exports configuration files, and generates a minimal changelog.md if missing. Managed files (workflows, configs, skills) are always overwritten. The user-owned changelog is created once and never overwritten.

For awesome-* repositories, the awesome-template component joins a bare init through its AWESOME_ONLY scope.

Note

Scope exclusions (RepoScope.AWESOME_ONLY, PYTHON_ONLY) and user-config exclusions ([tool.repomatic] exclude) only apply during bare repomatic init. When components are explicitly named on the CLI, scope is bypassed: the caller knows what they asked for. This allows workflows to materialize out-of-scope configs at runtime (like repomatic init publish-pypi-action in a non-Python repo).

Parameters:

• output_dir (Path) – Root directory of the target repository.

• components (Sequence[str]) – Components to initialize. Empty means all defaults. When non-empty, scope and user-config exclusions are bypassed.

• config (Config) – The resolved [tool.repomatic] configuration of the target.

• version (str | None) – Version pin for upstream workflows (like v5.10.0). When None, derived from the running package version, gated by cooldown.

• cooldown (bool) – When True (and version is unset), hold the derived pin back to the newest release past the [tool.repomatic] minimum-release-age window instead of pinning a fresh running version (see resolve_default_pin()). Ignored when version is explicit.

• repo (str) – Upstream repository containing reusable workflows.

• repo_slug (str | None) – Repository owner/name slug, for the awesome-template URL rewriting and the changelog stub. Read from Metadata on first use when omitted.

Return type:

InitResult

Returns:

Summary of created, updated, skipped, and warned items.