# Command-line reference
Every subcommand and every option `cargo-gamma` accepts.
## Contents
* [Invoking the tool](#invoking-the-tool)
* [The subcommands](#the-subcommands)
* [The option categories](#the-option-categories)
* [Where settings come from](#where-settings-come-from)
* [Passing arguments through](#passing-arguments-through)
* [Resuming interrupted testing](#resuming-interrupted-testing)
* [Exact-first adaptive scheduling](#exact-first-adaptive-scheduling)
* [Understanding uncovered mutants](#understanding-uncovered-mutants)
* [Exit status](#exit-status)
* [Full option reference](#full-option-reference)
* [Accepted by every subcommand](#accepted-by-every-subcommand)
* [`gamma run`](#gamma-run)
* [`gamma list`](#gamma-list)
* [`gamma list mutants`](#gamma-list-mutants)
* [`gamma list files`](#gamma-list-files)
* [`gamma list mutators`](#gamma-list-mutators)
* [`gamma list presets`](#gamma-list-presets)
* [`gamma explain`](#gamma-explain)
* [`gamma suppress`](#gamma-suppress)
* [`gamma unsuppress`](#gamma-unsuppress)
* [`gamma merge`](#gamma-merge)
* [`gamma hints`](#gamma-hints)
* [`gamma clean`](#gamma-clean)
* [`gamma completions`](#gamma-completions)
## Invoking the tool
`cargo-gamma` is a cargo subcommand, so it is spelled with a space:
```bash
cargo gamma run
```
With no subcommand, `run` is implied, so these are the same:
```bash
cargo gamma
cargo gamma run
```
That shorthand only applies when the first argument is not itself a subcommand. `cargo gamma --workspace`
is a run over the whole workspace; `cargo gamma list` is the `list` subcommand and not a run.
## The subcommands
| [`gamma run`](#gamma-run) | Run mutation testing |
| [`gamma list`](#gamma-list) | List what would be done, without doing it |
| [`gamma explain`](#gamma-explain) | Explain a mutator, a mutant, or a suppression |
| [`gamma suppress`](#gamma-suppress) | Write suppressions into the source for mutants that cannot usefully be tested |
| [`gamma unsuppress`](#gamma-unsuppress) | Remove skip directives that no longer suppress anything |
| [`gamma merge`](#gamma-merge) | Combine per-shard reports into one answer |
| [`gamma hints`](#gamma-hints) | Promote what a run learned about speed into a file the workspace can check in |
| [`gamma clean`](#gamma-clean) | Delete cargo-gamma's cached data for a workspace |
| [`gamma completions`](#gamma-completions) | Print a shell completion script |
`gamma list` defaults to `mutants`. Its explicit modes are:
| `mutants` | List the current selected mutant population. |
| `files` | List source files in the selected population. |
| `mutators` | List registered mutators and their selection state. |
| `presets` | List named mutator presets. |
`--re` selects mutants for `run` and `list`; `list files` shows files containing a selected mutant.
`unsuppress` rejects `--re`, because a name filter cannot establish that a skip directive is idle
across its full source file.
An unsharded report generated with `--re` contains only matching mutants. `merge` retains older
verdicts for other mutants in the same file; use an unfiltered run or `list mutants --json-report`
to establish the current complete population and withdraw retired mutants.
## Exact-first adaptive scheduling
Every campaign uses exact-first adaptive scheduling:
```bash
cargo gamma run --diag
```
Exact hinted tests drain across the population first. Each worker then takes
one unresolved mutant through the remaining stages before claiming another:
1. Run exact hinted killing tests.
2. Run at most six eligible distinct inferred cases individually in ranked order,
under either libtest or nextest, without grouping cases by binary.
3. Run all inferred full binaries, best-first.
4. Run remaining reachable full binaries, reusing full-binary results from phase 3.
Fallback tries own-package binaries first, then other eligible binaries. Within
each tier, binaries with more distinct mutant kills run first; baseline runtime
and stable identity break ties. Counts include known exact hints and observed
kills discovered during this campaign, without crediting the same mutant twice.
The ordering is refreshed when each mutant enters fallback and does not change
final non-killing outcome precedence.
Full-binary discoveries immediately supply hints for queued mutants. Assignment
preserves package fairness, exploits fresh effective same-function killers, and
spreads discovery across independent functions according to sibling benefit per
estimated cost. Repeated transfer misses reduce the function's priority boost
without retiring its candidates. Same-function siblings remain runnable when
there is no independent work.
Every kill settles immediately, without waiting for earlier binaries.
Each mutant runs one selection at a time; parallelism is across mutants, up to
the configured job count in every phase. Gamma imposes no additional CPU-count cap
or aggregate memory reservation. Reduce `--jobs` if concurrent runs exhaust system
memory. Per-process memory limits and declared named-resource capacities remain
enforced. Nextest retains
process-per-test isolation and executes one test process at a time per mutant.
Resource retries, nextest enumeration controls, and configured nextest retries are separate from phase-2
candidate limits. Passing selected cases never establishes survival.
Baseline harness-thread settings, memory ceilings, named-resource limits, resource retries, and
nextest enumeration controls remain in force. Diagnostic accounting records execution-tier
costs. Snapshots from earlier scheduler policies require a new campaign rather
than resuming under a different verdict policy.
## Resuming interrupted testing
After CTRL+C during the mutant-testing phase, continue that same campaign with:
```bash
cargo gamma run --resume-testing
```
The prepared workspace and test binaries are reused as-is. Discovery, copying,
instrumentation, builds, and baseline measurement do not
run again. All completed verdicts are retained; unfinished mutants are retried.
Selection and test settings are frozen, so live source changes, execution settings
in `gamma.toml`, new hints, and suppression edits do not alter the resumed
campaign. Reporting options remain live; `min-score` and `max-flaky` gates are
read from current configuration unless overridden on the command line. Unrelated
execution values are not validated on resume, but unknown top-level configuration
keys are rejected. Use `--dir` and, if necessary,
`--cache-dir` to identify the existing campaign.
Prepared snapshot schema version 3 rejects older reachability- or kill-confirmation-policy snapshots;
their settled no-coverage verdicts cannot be safely reused. Start a fresh
campaign instead of resuming those snapshots.
Resume reports an error if the campaign did not reach testing, already published
its completed ledger, or has incompatible or corrupt state. When tests remain
pending, prepared artifacts and the inherited environment must remain unchanged,
and the host must still support the campaign's execution requirements. If testing finished
but completed-ledger publication was interrupted, resume publishes the result
without rerunning mutants, requiring prepared files or binaries, or requiring host
execution capabilities or the current inherited environment to match. The saved
snapshot, verdict checksums, campaign identity, and captured source generation
are still validated; reports use the captured source, not the live checkout.
It never falls back to starting a new campaign. Only
campaigns started by a version supporting this option have resumable state;
older diagnostic progress logs cannot be resumed.
Before starting a new campaign, cargo-gamma checks whether its previous completed
ledger can be updated. An unsupported record format is refused before discovery
or execution. Move the named `last-gamma-run.json` to a separate archive path to
preserve its evidence, then retry. If an older ledger blocked publication after
testing finished, archive that ledger and use `--resume-testing` to publish the
new results without rerunning tests. Do not remove the testing snapshot or journal.
`cargo gamma hints`, `cargo gamma suppress`, and `cargo gamma unsuppress` can
also be used after interruption. Hints and suppressions use the current partial
campaign's recorded evidence rather than an older completed campaign. Pending
mutants supply no verdict. Suppression and unsuppression preview edits unless
`--apply` is passed, and their source-validation safeguards still apply.
`hints --replace` is the exception: whole-artifact replacement requires a valid
completed campaign ledger and never uses the interrupted checkpoint.
Sweep measurements are also available without changing the live display.
Completed diagnostics contain optional `phases.sweep.accounting`, and the private
campaign base contains `gamma-sweep-live.json` with current accounting and
`sweepWallMs`. Measurements distinguish initial exact-hint coverage, observed
confirmation of original killers, runner attempts and time by execution tier,
confirmation work, and duplicate attempts avoided. Runner attempts are not a
physical process count; summed concurrent execution time is not wall-clock time.
Resume retains cumulative measurements without counting replayed snapshots twice.
Unknown legacy coverage remains unknown.
## The option categories
The same categories appear in `--help` and in the reference below. Knowing which category a setting
lives in is usually enough to find it:
| **Selecting what to mutate** | Which files, packages, lines and mutators make up the population. Applied before anything is built. |
| **Cargo features** | The feature set to compile under. Discovery and the build must agree, so these apply to both. |
| **Configuration** | Where settings are read from, and whether the file is read at all. |
| **Building** | Compiler convergence and test-binary generation: profile, arguments to Cargo, timeouts, and how many withdrawal rounds are allowed. |
| **Running tests** | How the suite is executed per mutant: parallelism, timeouts, which test targets may decide a verdict, and which runner. |
| **Memory** | The ceiling each test binary runs under, and how it is derived. A mutant can turn bounded allocation into unbounded allocation, which a timeout catches only slowly. |
| **Scratch tree** | Where the instrumented copy of the workspace lives, and what is copied into it. |
| **Run control** | What the run does as a whole: gate on a score, reuse safe knowledge from a previous run, or stop early. |
| **Reporting** | What is written where, and how much detail the console prints. |
| **Global options** | Color, accepted by every subcommand. Progress display settings are run control. |
Two categories are specific to one subcommand: **Suppressing** (`suppress`, `unsuppress`) and
**Merging** (`merge`).
## Where settings come from
A setting can be given in three places. Later beats earlier:
1. **The built-in default.**
2. **The configuration file**, `gamma.toml` by default — see [CONFIG.md](CONFIG.md) for every
key, and [`gamma.toml`](gamma.toml) for a documented file to copy.
3. **The command line.**
So a flag always wins over the file, and `--no-config` ignores the file entirely — which is what
makes a scripted run reproducible regardless of what the project happens to have committed.
Not every option has a configuration key, and not every key has an option. A key with no flag is
noted in [CONFIG.md](CONFIG.md); an option with no key is generally one that makes no sense to
persist, such as `--dry-run`.
## Passing arguments through
Three options forward arguments to something else, and they are not interchangeable:
| `--cargo-arg`, `-C` | every **cargo** invocation | `--offline`, `--locked`, `--target`, and other build arguments (not Cargo `--config`; use a configuration file gamma can inspect) |
| `--cargo-test-arg` | every **test binary** | harness arguments, in a form a configuration file can hold |
| `--` (trailing) | every **test binary** | the same thing, typed at the shell |
`--cargo-test-arg` and `--` mean the same thing to the harness and are concatenated. Both exist
because a configuration file cannot express a positional `--`, and because `--` must come last, so
nothing can follow it:
```bash
cargo gamma run --cargo-arg --offline -- --test-threads=1
```
## Compiler exclusions
Before generating mutation guards, campaigns filter exact mutant IDs in
`compiler-exclusions.json` under the campaign cache. These mutants count as
unviable without being applied or recompiled. The inventory accumulates
individually established compiler failures across campaigns, including interrupted
preparation, and is initialized from earlier completed/incomplete records and
`gamma-hints.yaml`. Compiler-interaction removals do not enter it.
This is an explicit exclusion policy, not an incremental-cache optimization:
`--incremental no`, feature changes, and toolchain changes do not disable it.
To retry a repaired mutant, remove its entry and use `--incremental no` to avoid
ordinary cached compiler outcomes. An existing inventory is authoritative;
removing the entire file permits old evidence to be imported again. `--dry-run`
applies the policy without modifying the inventory; raw candidate listings do not.
The Excluding display shows confirmed counts as they are discovered, including
historical exclusions, without check or proof counters. Compilation keeps the
initial pristine validation's package roots and target scope throughout; isolation
does not repeatedly compile pristine source or widen the feature graph.
## Understanding uncovered mutants
`uncovered` means cargo-gamma obtained complete, deterministic evidence that no selected runtime
test activated the mutation site's guard. That evidence comes from sealed, passing whole-binary
observations learned while testing another replacement at the
same stable site. It does not mean that every external coverage report must show the source line as
missed. `--whole-test-binaries` disables deterministic reach narrowing, so this case-level
classification is unavailable.
For example, code annotated `#[coverage(off)]` is removed from a coverage tool's denominator but
remains production code that gamma mutates. A project can therefore report 100% line coverage while
gamma correctly reports an uncovered mutant in that function. Coverage combined across other
platforms, features or test targets can create the same difference, as can cfg-disabled or
compile-time proc-macro code. Line coverage can also mark a line while a particular expression or
branch on it never ran.
Respond according to intent: add a runtime test, align the run's features/platform/test-targets with
the coverage job, or use a reviewed [suppression](../README.md#suppressing-mutations) for code that
is intentionally outside the mutation oracle. Gamma does not automatically exclude
`#[coverage(off)]`, because deliberately uncounted code can still contain behavior worth testing.
## Test environment
Cargo-gamma builds test targets through Cargo and then reuses those binaries directly or through
nextest. Direct launches reproduce Cargo's runtime environment, including package and manifest
metadata, build-script environment and `OUT_DIR`, integration-test `CARGO_BIN_EXE_*` paths, the
selected Cargo/rustup toolchain, the package working directory, and executable and dynamic-library
search paths. With `--nextest`, cargo-gamma supplies the Cargo context and nextest adds its
runner-specific `NEXTEST_*` variables.
## Exit status
The process status distinguishes a rejected invocation, a completed campaign whose correctness
gate failed, and a campaign that could not obtain a complete answer:
| `0` | The command completed and every requested gate or expectation passed. Help and version also return success. |
| `1` | The command line, configuration, or effective selection was invalid. |
| `2` | The command completed, but a score gate or source expectation failed, or a requested gate had no complete population to grade. |
| `3` | The command could not proceed or could not produce the requested complete result. |
| `70` | An internal cargo-gamma panic reached the top-level boundary. |
An `--in-diff` run that selects no mutants succeeds, even with `--min-score` or `--max-flaky`
configured. This applies to the final selection after combining diff scope with other filters,
such as `--re` and sharding, not only to a diff with no mutable lines. Other empty populations fail
when a configured gate requires something to grade. A nonempty population consisting entirely of excluded or
otherwise ungradeable mutants still fails the applicable gate, including with `--in-diff`. A partially
completed population fails when either `--min-score` or `--max-flaky` is configured; with no strict
gate it remains a reportable result. Build convergence that leaves stuck mutants is still status
`3`, because the selected population was not built completely enough to answer.
A failing baseline also returns status `3`. Cargo-gamma lets completing baseline binaries report
all their test failures, writes each failure under
`target/cargo-gamma/baseline-failures/<package>/<target>/` (or the equivalent beneath
`--artifact-dir`). It prints a platform-native `Wrote` path for the canonical diagnostics and each
failure's `failure.json` and `diags.json`, then one aggregate error directing the reader there. A
new build clears that directory first, so every retained record belongs to the current run. Because
the instrumented build has already converged before baselining, these diagnostics retain the full
mutant population and its known unviable and still-pending outcomes even when the baseline fails.
## Diff scope and limitations
`--in-diff` selects mutation sites that overlap added or changed production-code lines. It does
not perform test-impact analysis: changing or deleting tests does not select mutants in the
unchanged production code those tests exercised. A PR that deletes every test without changing
production code can therefore select no mutants and succeed, even with score and flaky gates enabled.
Deletions alone provide no new lines to mutate.
A passing diff-scoped run establishes nothing about test protection outside its selected mutation
sites. Use it for faster feedback, not as a substitute for full mutation testing. To detect lost
protection in unchanged code, run without `--in-diff`; CI can do this whenever tests or test
configuration change, in addition to periodic full runs.
## Baseline and kill attribution
Baseline runs the selected healthy tests before the sweep. Ordinary failures with a mutant active
then count as kills without an additional unmutated run, including failures from hinted tests.
A passing baseline does not rule out intermittent assertion failures later, which can count as
kills. New flaky verdicts arise only from unmutated nextest enumeration controls: a failed test or
a control that times out, stalls or exceeds its memory ceiling leaves the mutant unjudged in that
score-neutral bucket. `--max-flaky` gates those verdicts, not ordinary intermittent assertion failures.
Merge also retains and gates flaky verdicts in historical reports. Timeout, stall and memory
suspicions retain their retries.
`--no-confirm` and `no-confirm` are unsupported; omit them from commands and configuration.
## Full option reference
`--help` and `--version` are accepted everywhere and are omitted below. Options marked with a
default take that value when neither the command line nor the configuration file sets one.
### Accepted by every subcommand
**Global options**
| `--color` | `<WHEN>` | When to use color in output. Defaults to `auto`. |
### `gamma run`
Run mutation testing
```text
cargo gamma run [OPTIONS] [-- <TEST_ARGS>...]
```
**Run control**
| `--resume-testing` | | Continue the interrupted campaign's testing phase using its existing prepared tree. |
| `--update-hints` | | Promote the campaign's learned hints after it reaches a reportable outcome. |
| `--progress` | `<WHEN>` | When to show the progress display. Defaults to `auto`. |
| `--dashboard` | | Show a live testing dashboard instead of the progress bar. |
| `--min-score` | `<PERCENT>` | Fail the run if the assertion-killed mutation score is below this percentage. |
| `--max-flaky` | `<COUNT>` | Fail if more than this many mutants have an unresolved flaky outcome. |
| `--incremental` | `<INCREMENTAL>` | How an incremental run reuses the last run: `no` starts cold; `build` reuses compiler unviability and checked execution hints. |
| `--leak-dirs` | | Keep an incomplete scratch workspace after errors so it can be inspected. |
| `--no-baseline` | | Skip the baseline run. |
| `--dry-run` | | Find and report mutants without building or running anything. |
| `--no-stall-detection` | | Wait out the whole budget for every mutant instead of cutting off one that has stopped making progress. |
**Selecting what to mutate**
| `-d`, `--dir` | `<PATH>` | Path to the workspace or package to analyze. Defaults to `.`. |
| `--mutators` | `<SELECTORS>` | Mutators to apply, as a comma-separated selector list. |
| `--file` | `<GLOB>` | Only mutate files matching these glob patterns. |
| `--exclude-file` | `<GLOB>` | Skip files matching these glob patterns. |
| `--re` | `<REGEX>` | Only select mutants whose listed name matches this regular expression. Repeat to match any. |
| `--shard-count` | `<COUNT>` | Number of shards to divide the mutants into. |
| `--shard-index` | `<INDEX>` | Which shard to run, from 0. |
| `-D`, `--in-diff` | `<PATH>` | Only mutate lines added or changed by this unified diff, or `-` for standard input. |
| `-p`, `--package` | `<NAME>` | Only mutate these packages. Defaults to Cargo's package selection for the current directory. |
| `--workspace` | | Mutate every package in the workspace. |
| `--error` | `<EXPR>` | Additional values for `fn_value.err_with`, which replaces a function body with `Err(...)`. |
| `--only-survivors` | | Run only mutants that genuinely survived in the previous cargo-gamma report. |
| `--mutant` | `<ID>` | Run exactly this current mutant ID; repeat to select more than one. |
**Cargo features**
| `--features` | `<FEATURES>` | Cargo features to activate, comma-separated or repeated. |
| `--all-features` | | Activate every feature of every selected package. |
| `--no-default-features` | | Do not activate the `default` feature. |
**Configuration**
| `--config` | `<PATH>` | Read configuration from this file instead of `gamma.toml`. |
| `--no-config` | | Ignore the configuration file entirely. |
**Running tests**
| `--show-build` | | Show Cargo's raw build output. |
| `-j`, `--jobs` | `<N>` | How many mutants to test at once. Defaults to one more than the available parallelism. |
| `--resource-concurrency` | `<NAME=N>` | Override the maximum concurrency of a test resource declared with `#[gamma::resource]`. |
| `--test-timeout-multiplier` | `<FACTOR>` | Multiple of each test binary's baseline duration that a mutant is allowed. |
| `--minimum-test-timeout` | `<SECONDS>` | Lower bound on a test binary's timeout, however fast the baseline was. |
| `--cargo-test-arg` | `<ARG>` | Pass an argument through to every test binary. |
| `--test-package` | `<NAME>` | Run the tests of these packages when deciding a verdict. |
| `--test-lib` | | Use only library unit-test harnesses as the verdict oracle. |
| `--include-test` | `<GLOB>` | Only let these test targets decide a verdict. |
| `--exclude-test` | `<GLOB>` | Do not let these test targets decide a verdict. |
| `--nextest` | | Run test binaries through `cargo nextest` for per-test process isolation. |
| `--test-workspace` | | Let every workspace package's tests decide a verdict. |
| `--whole-test-binaries` | | Run every selected test in each reachable test binary. |
**Memory**
| `--memory` | `<MODE>` | How much memory control to place around each test binary. `enforce` by default. |
| `--memory-multiplier` | `<FACTOR>` | Multiple of a test binary's baseline peak memory a mutant of it may reach. |
| `--memory-headroom` | `<SIZE>` | Absolute headroom added to a test binary's baseline peak memory. |
| `--memory-limit` | `<SIZE>` | An explicit memory ceiling for every test binary, instead of one derived from the baseline. |
| `--baseline-memory-limit` | `<SIZE>` | A memory ceiling for the baseline runs themselves. |
| `--no-relaunch` | | Do not re-run inside a systemd scope to obtain the cgroup memory control needs. |
**Building**
| `--profile` | `<NAME>` | Which Cargo profile to build with. |
| `-C`, `--cargo-arg` | `<ARG>` | Pass an argument through to every cargo invocation. |
| `--build-timeout` | `<SECONDS>` | Seconds a compiler invocation may take before the run is abandoned. |
| `--build-timeout-multiplier` | `<FACTOR>` | Multiple of the first compiler round's duration that a later round is allowed. |
| `--rollback-rounds` | `<ROUNDS>` | How many compiler rounds may withdraw mutants that do not compile. Defaults to `256`. |
**Cache**
| `--cache-dir` | `<PATH>` | Put cargo-gamma's reusable workspace and Cargo artifacts in this directory. |
| `--copy-ignored` | | Copy files version control ignores into the cached workspace as well. |
**Arguments**
| `<TEST_ARGS>` | `<TEST_ARGS>` | Arguments passed to every test binary, after `--`. |
**Reporting**
| `--artifact-dir` | `<PATH>` | Write all user-facing artifacts to this directory. |
| `--show-killed` | | List the mutants the suite killed, not just the ones that survived. |
| `--show-unviable` | | List every mutant that could not be compiled, not just how many there were. |
| `--sarif-level` | `<LEVEL>` | How loudly a survivor is reported to a SARIF consumer. Defaults to `note`. |
| `--annotations` | `<WHEN>` | Annotate the diff and write a job summary when running inside a CI system. Defaults to `auto`. |
| `--diag-names` | `<POLICY>` | What to do with package and binary names in the diagnostics bundle. Defaults to `hashed`. |
### `gamma list`
List what would be done, without doing it
```text
cargo gamma list <COMMAND>
```
### `gamma list mutants`
List the mutants that would be generated
```text
cargo gamma list mutants [OPTIONS]
```
**Selecting what to mutate**
| `-d`, `--dir` | `<PATH>` | Path to the workspace or package to analyze. Defaults to `.`. |
| `--mutators` | `<SELECTORS>` | Mutators to apply, as a comma-separated selector list. |
| `--file` | `<GLOB>` | Only mutate files matching these glob patterns. |
| `--exclude-file` | `<GLOB>` | Skip files matching these glob patterns. |
| `--re` | `<REGEX>` | Only select mutants whose listed name matches this regular expression. Repeat to match any. |
| `--shard-count` | `<COUNT>` | Number of shards to divide the mutants into. |
| `--shard-index` | `<INDEX>` | Which shard to run, from 0. |
| `-D`, `--in-diff` | `<PATH>` | Only mutate lines added or changed by this unified diff, or `-` for standard input. |
| `-p`, `--package` | `<NAME>` | Only mutate these packages. Defaults to Cargo's package selection for the current directory. |
| `--workspace` | | Mutate every package in the workspace. |
| `--error` | `<EXPR>` | Additional values for `fn_value.err_with`, which replaces a function body with `Err(...)`. |
**Cargo features**
| `--features` | `<FEATURES>` | Cargo features to activate, comma-separated or repeated. |
| `--all-features` | | Activate every feature of every selected package. |
| `--no-default-features` | | Do not activate the `default` feature. |
**Configuration**
| `--config` | `<PATH>` | Read configuration from this file instead of `gamma.toml`. |
| `--no-config` | | Ignore the configuration file entirely. |
**Reporting**
| `--json` | | Emit machine-readable JSON instead of text. |
| `--json-report` | `<PATH>` | Write the population as a report document, for `merge` to withdraw retired mutants against. |
### `gamma list files`
List the source files that would be analyzed
```text
cargo gamma list files [OPTIONS]
```
**Selecting what to mutate**
| `-d`, `--dir` | `<PATH>` | Path to the workspace or package to analyze. Defaults to `.`. |
| `--mutators` | `<SELECTORS>` | Mutators to apply, as a comma-separated selector list. |
| `--file` | `<GLOB>` | Only mutate files matching these glob patterns. |
| `--exclude-file` | `<GLOB>` | Skip files matching these glob patterns. |
| `--re` | `<REGEX>` | Only select mutants whose listed name matches this regular expression. Repeat to match any. |
| `--shard-count` | `<COUNT>` | Number of shards to divide the mutants into. |
| `--shard-index` | `<INDEX>` | Which shard to run, from 0. |
| `-D`, `--in-diff` | `<PATH>` | Only mutate lines added or changed by this unified diff, or `-` for standard input. |
| `-p`, `--package` | `<NAME>` | Only mutate these packages. Defaults to Cargo's package selection for the current directory. |
| `--workspace` | | Mutate every package in the workspace. |
| `--error` | `<EXPR>` | Additional values for `fn_value.err_with`, which replaces a function body with `Err(...)`. |
**Cargo features**
| `--features` | `<FEATURES>` | Cargo features to activate, comma-separated or repeated. |
| `--all-features` | | Activate every feature of every selected package. |
| `--no-default-features` | | Do not activate the `default` feature. |
**Configuration**
| `--config` | `<PATH>` | Read configuration from this file instead of `gamma.toml`. |
| `--no-config` | | Ignore the configuration file entirely. |
**Reporting**
| `--json` | | Emit machine-readable JSON instead of text. |
### `gamma list mutators`
List the mutator registry
```text
cargo gamma list mutators [OPTIONS]
```
**Selecting mutators**
| `-d`, `--dir` | `<PATH>` | Path used to find `gamma.toml`. Defaults to `.`. |
| `--mutators` | `<SELECTORS>` | Mutators to mark as enabled, as a comma-separated selector list. |
**Configuration**
| `--config` | `<PATH>` | Read configuration from this file instead of `gamma.toml`. |
| `--no-config` | | Ignore the configuration file entirely. |
**Reporting**
| `--json` | | Emit machine-readable JSON instead of text. |
### `gamma list presets`
List the named mutator presets
```text
cargo gamma list presets [OPTIONS]
```
**Selecting mutators**
| `-d`, `--dir` | `<PATH>` | Path used to find `gamma.toml`. Defaults to `.`. |
| `--mutators` | `<SELECTORS>` | Mutators to mark as enabled, as a comma-separated selector list. |
**Configuration**
| `--config` | `<PATH>` | Read configuration from this file instead of `gamma.toml`. |
| `--no-config` | | Ignore the configuration file entirely. |
**Reporting**
| `--json` | | Emit machine-readable JSON instead of text. |
### `gamma explain`
Explain a mutator, a mutant, or a suppression
```text
cargo gamma explain [OPTIONS] <SUBJECT>
```
**Arguments**
| `<SUBJECT>` | `<SUBJECT>` | A mutator name, family, preset, or mutant id. |
**Selecting current mutants**
| `-d`, `--dir` | `<PATH>` | Path to the workspace used to resolve a current mutant ID. Defaults to `.`. |
| `-p`, `--package` | `<NAME>` | Restrict current discovery to these packages. |
| `--workspace` | | Resolve current mutants across every workspace package. |
**Reporting**
| `--report` | `<PATH>` | Read historical verdict context from this cargo-gamma JSON report. |
**Cargo features**
| `--features` | `<FEATURES>` | Cargo features to activate, comma-separated or repeated. |
| `--all-features` | | Activate every feature of every selected package. |
| `--no-default-features` | | Do not activate the `default` feature. |
**Configuration**
| `--config` | `<PATH>` | Read configuration from this file instead of `gamma.toml`. |
| `--no-config` | | Ignore the configuration file entirely. |
### `gamma suppress`
Write suppressions into the source for mutants that cannot usefully be tested
```text
cargo gamma suppress [OPTIONS]
```
**Suppressing**
| `-d`, `--dir` | `<PATH>` | Path to the workspace or package whose latest campaign should be used. Defaults to `.`. |
| `--apply` | | Write and verify the generated directives instead of printing the proposed diff. |
| `--eligible` | `<LIST>` | Which verdicts may be suppressed. Defaults to `timeout,outofmem`. |
| `--allow-dirty` | | Edit source files that have uncommitted changes. |
**Cache**
| `--cache-dir` | `<PATH>` | Read completed or interrupted testing evidence from this cache directory. |
### `gamma unsuppress`
Remove skip directives that no longer suppress anything
```text
cargo gamma unsuppress [OPTIONS]
```
**Selecting what to mutate**
| `-d`, `--dir` | `<PATH>` | Path to the workspace or package to analyze. Defaults to `.`. |
| `--mutators` | `<SELECTORS>` | Mutators to apply, as a comma-separated selector list. |
| `--file` | `<GLOB>` | Only mutate files matching these glob patterns. |
| `--exclude-file` | `<GLOB>` | Skip files matching these glob patterns. |
| `--re` | `<REGEX>` | Only select mutants whose listed name matches this regular expression. Repeat to match any. |
| `--shard-count` | `<COUNT>` | Number of shards to divide the mutants into. |
| `--shard-index` | `<INDEX>` | Which shard to run, from 0. |
| `-D`, `--in-diff` | `<PATH>` | Only mutate lines added or changed by this unified diff, or `-` for standard input. |
| `-p`, `--package` | `<NAME>` | Only mutate these packages. Defaults to Cargo's package selection for the current directory. |
| `--workspace` | | Mutate every package in the workspace. |
| `--error` | `<EXPR>` | Additional values for `fn_value.err_with`, which replaces a function body with `Err(...)`. |
**Cargo features**
| `--features` | `<FEATURES>` | Cargo features to activate, comma-separated or repeated. |
| `--all-features` | | Activate every feature of every selected package. |
| `--no-default-features` | | Do not activate the `default` feature. |
**Configuration**
| `--config` | `<PATH>` | Read configuration from this file instead of `gamma.toml`. |
| `--no-config` | | Ignore the configuration file entirely. |
**Suppressing**
| `--apply` | | Remove the directives instead of printing what would be removed. |
| `--allow-dirty` | | Remove directives from source files that have uncommitted changes. |
### `gamma merge`
Combine per-shard reports into one answer
```text
cargo gamma merge [OPTIONS] <REPORTS>...
```
**Arguments**
| `<INPUTS>` | `<REPORTS>` | The reports to merge. A directory is read for its `*.json` files. |
**Reporting**
| `--json-report` | `<PATH>` | Write the merged `mutation-testing-elements` document here. |
| `--html-report` | `<PATH>` | Write a self-contained merged HTML report here. |
**Merging**
| `--window` | `<DAYS>` | Days after which a verdict is reported as stale. Zero disables the freshness window. Defaults to `30`. |
**Run control**
| `--min-score` | `<PERCENT>` | Fail if the merged assertion-killed score is below this percentage. |
| `--max-flaky` | `<COUNT>` | Fail if more than this many merged mutants have an unresolved flaky outcome. |
### `gamma hints`
Promote what a run learned about speed into a file the workspace can check in
```text
cargo gamma hints [OPTIONS]
```
**Options**
| `-d`, `--dir` | `<PATH>` | Path to the workspace or package whose latest campaign knowledge should be promoted. Defaults to `.`. |
**Cache**
| `--cache-dir` | `<PATH>` | Read the run record from this cache directory instead of cargo-gamma's default. |
**Run control**
| `--dry-run` | | Report what would be promoted without writing anything. |
| `--replace` | | Replace the complete hints artifact instead of merging the recorded campaign into it. |
### `gamma clean`
Delete cargo-gamma's cached data for a workspace
```text
cargo gamma clean [OPTIONS]
```
**Options**
| `-d`, `--dir` | `<PATH>` | Path to the workspace or package whose cache should be deleted. Defaults to `.`. |
### `gamma completions`
Print a shell completion script
```text
cargo gamma completions <SHELL>
```
**Arguments**
| `<SHELL>` | `<SHELL>` | The shell to generate a completion script for. |