repomatic.cli package

The repomatic command-line interface.

main holds the group, its help sections and the shared plumbing; each sibling module carries one help section’s commands and registers them onto the group at import time.

Submodules

repomatic.cli.github module

GitHub issue and pull request commands of the repomatic CLI.

One module per help section: every command here registers onto the repomatic group through the section object both import from repomatic.cli.main, which pulls this module in at startup.

repomatic.cli.lint module

Linting and verification commands of the repomatic CLI.

One module per help section: every command here registers onto the repomatic group through the section object both import from repomatic.cli.main, which pulls this module in at startup.

repomatic.cli.main module

The repomatic command-line group and its shared plumbing.

Commands live in the per-section cli_* sibling modules and register onto the group defined here; the bottom of this module imports them for that side effect. What stays here is everything they share: the group, its help sections, the reusable option declarations, the parameter types, and the small helpers command bodies lean on.

repomatic.cli.main.exit_if_disabled(ctx, enabled, key)

Exit successfully when a [tool.repomatic] feature flag is off.

The shared guard of every sync command: a disabled feature is a normal, configured state, so the command logs the flag and exits 0 instead of failing the workflow that invoked it.

Parameters:

• ctx (Context) – The Click context to exit through.

• enabled (bool) – The resolved feature flag value.

• key (str) – The [tool.repomatic] key, in kebab-case, for the log line.

Return type:

None

repomatic.cli.main.log_output_target(subject, output)

Log where a command is about to write subject.

Every command that honors an --output path narrates the destination the same way, distinguishing the stdout case (-) so the log names the stream instead of a literal dash.

Parameters:

• subject (str) – What is being written, as a noun phrase ("metadata", "PR body").

• output (Path) – The resolved --output path.

Return type:

None

class repomatic.cli.main.ComponentSelector

Bases: ParamType

Accepts bare component names or qualified component/file selectors.

Bare names (e.g., skills) select an entire component. Qualified entries (e.g., skills/repomatic-topics) select a single file within a component. Validation delegates to parse_component_entries(), the same code path the exclude and include config options go through, so the CLI and config agree on syntax and error messages.

name: str = 'selector'

the descriptive name of this type

get_metavar(param, ctx)

Returns the metavar default for this param if it provides one.

Return type:

str

convert(value, param, ctx)

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters:

• value (Any) – The value to convert.

• param (Parameter | None) – The parameter that is using this type to convert its value. May be None.

• ctx (Context | None) – The current context that arrived at this value. May be None.

Return type:

str

shell_complete(ctx, param, incomplete)

Return a list of CompletionItem objects for the incomplete value. Most types do not provide completions, but some do, and this allows custom types to provide custom completions as well.

Parameters:

• ctx (Context) – Invocation context for this command.

• param (Parameter) – The parameter that is requesting completion.

• incomplete (str) – Value being completed. May be empty.

Added in version 8.0.

Return type:

list[CompletionItem]

repomatic.cli.main.AXIS_HEADER_LABELS = {'os': 'OS', 'python-version': 'Python', 'state': 'State'}

Display names for the job keys show-test-matrix heads a row or column with.

A key absent from here heads its column under the raw name a matrix declares it as, which is also how a caller names it on the command line.

repomatic.cli.main.JOB_COUNT_MARK = '×'

Introduces the job count of a cell standing for more than one job.

A cell collapses every job at its intersection, so a matrix varying on a third axis renders five jobs exactly like one. The mark is the East Asian Ambiguous U+00D7, like the — placeholder the grid already uses: a terminal drawing ambiguous characters double-width misaligns both alike, and neither before the other.

repomatic.cli.main.TEST_MATRIX_STATE_DISPLAY = {'stable': '✅ stable', 'unstable': '⁉️ unstable'}

Emoji-decorated labels for job states in the show-test-matrix grid.

The same two glyphs the workflow templates stamp onto each matrix job’s name, and that repomatic.github.ci_status.JobStatus.required() reads back off it, so the grid and the CI verdict cannot come to disagree about which mark means “allowed to fail”.

Caution

UNSTABLE_GLYPH is an emoji-presentation sequence (U+2049 followed by the U+FE0F selector), and that is the one class of glyph terminals measure differently: wcwidth counts it as two columns and the table renderer pads to that, while a terminal allocating a single cell for it (Apple Terminal does, painting the glyph over the space that follows) draws the row a column short of its own separators. Carrying the mark CI stamps is worth that, by decision: do not “fix” the alignment by dropping the selector here, which would leave the grid and the job names spelling the mark differently. --no-emoji sidesteps the whole question for a reader who wants a square grid, and a terminal on Unicode 9 widths never sees it.

repomatic.cli.main.matrix_axis_sort_key(axis, matrix_name)

Canonical ordering for one grid axis, or None to keep job order.

Keyed on which axis it is rather than on which side of the grid it landed: a transposed grid earns the runner order its columns get by default, and reads as arbitrarily shuffled without it. An axis the test matrix does not define an order for (a click-version) keeps the order the job stream presents it in, which is the matrix author’s own.

Return type:

Callable[[str], Any] | None

repomatic.cli.main.state_label(state, emoji=True)

Label one job state, glyph-decorated unless emoji says otherwise.

A state the matrix carries but this CLI has no label for renders as itself, so a new one shows up in the grid rather than vanishing from it.

Return type:

str

repomatic.cli.main.flat_matrix_table(jobs, leading=(), emoji=True)

Lay a solved job stream out as one row per job, one column per key.

A grid has two axes and collapses every other one into its cells, which is what a matrix varying on a third loses. Here each key is a column instead, so nothing collapses and the table is the job list CI will run.

Columns are collected across the whole stream, since a job may carry a key its neighbour does not (the python-label only a prerelease needs), and the state lands last as the outcome the other columns explain. A job missing a key renders empty there rather than shifting its row.

Parameters:

• jobs (Sequence[Mapping[str, str]]) – The solved job stream, already in the order to render.

• leading (Sequence[str]) – Keys to column first, in this order, before the ones the stream contributes. A listing sorted on an axis reads as unsorted with that axis buried in the middle, so the caller leads with the axes it ordered by. A key no job carries is skipped rather than columned empty.

• emoji (bool) – Label the state with its glyph rather than its bare word.

Return type:

tuple[tuple[str, ...], tuple[tuple[str, ...], ...]]

Returns:

A (headers, rows) pair, in the order print_table takes them the other way round.

repomatic.cli.main.format_matrix_cell(cell, tally, emoji=True)

Render one show-test-matrix cell from the jobs that landed in it.

Every state is labelled on its own. A cell holds more than one when the matrix carries an axis beyond its two (a click-version variation, say): both jobs land on the same intersection, and a label looked up for the joined string would match nothing and leave that cell the only bare one in its column.

A state carrying several jobs also states how many, since the grid gives a reader no other way to tell five stable jobs from one.

Parameters:

• cell (str) – The cell pivot() rendered, returned untouched when no job occupies the intersection: the placeholder for an empty one is that method’s to choose.

• tally (Counter[str] | None) – That intersection’s job count per state, or None where the matrix puts no job at all.

• emoji (bool) – Label each state with its glyph rather than its bare word. A count is not decoration, and shows either way.

Return type:

str

repomatic.cli.release module

Release and versioning commands of the repomatic CLI.

One module per help section: every command here registers onto the repomatic group through the section object both import from repomatic.cli.main, which pulls this module in at startup.

repomatic.cli.sample module

Forge sampling commands of the repomatic CLI.

One module per help section: every command here registers onto the repomatic group through the section object both import from repomatic.cli.main, which pulls this module in at startup.

repomatic.cli.setup module

Project setup and reporting commands of the repomatic CLI.

One module per help section: every command here registers onto the repomatic group through the section object both import from repomatic.cli.main, which pulls this module in at startup.

repomatic.cli.sync module

Sync commands of the repomatic CLI.

One module per help section: every command here registers onto the repomatic group through the section object both import from repomatic.cli.main, which pulls this module in at startup.