Configuration

.refquiem.toml sits at the workspace root, the directory whose Cargo.toml owns the scanned directory. Every key is optional, keys are kebab-case, and an unknown key is an error. --config PATH reads a different file, and a named file that is missing or unparseable is an error.

Keys

Key	Type	Meaning
exclude	array of strings	gitignore globs, relative to the workspace root, of files not scanned for mentions
allow	array of strings	paths and names never reported
generated-markers	array of strings	more phrases that mark a file as generated in its first five lines
scan-generated	boolean	scan generated files for mentions anyway, default false
scan-commented-code	boolean	scan comments that hold only Rust code, default false
since	string	the revision a scan of the full history starts at instead

exclude = ["docs/migration/"]
allow = ["Parser::parse_expr", "structopt"]
generated-markers = ["This file is generated"]
scan-commented-code = true
since = "v0.3.0"

Default excludes

Every scan applies these globs before the configured exclude globs, matched against the path below the workspace root.

CHANGELOG*
changelog/
RELEASES*
RELEASE-NOTES*
RELEASE_NOTES*
NEWS*
HISTORY*
CHANGES*

Generated files and commented code

A file counts as generated when one of its first five lines holds @generated, starts with // Code generated and ends with DO NOT EDIT., or contains a generated-markers phrase. Generated files are skipped for mentions unless scan-generated = true.

A comment whose content is entirely Rust code is commented-out code, and it is skipped unless scan-commented-code = true.

Scanned range

cargo refquiem --help lists all options, and cargo refquiem --version prints the binary version.

Command	Scanned	Compared against
none	every commit reachable from HEAD	the working tree
--since REV	REV and the commits after it, up to HEAD	the working tree
--base REV	REV plus the commits of REV..HEAD	the working tree
--base BASE --head HEAD	BASE plus the commits of BASE..HEAD	the specified head commit

• --head requires --base, and it reads the mentions from the committed tree of head, so uncommitted changes are not scanned.
• --since conflicts with --base.
• A revision that does not resolve to a commit is an error with exit 2.
• The since key applies only when the command names no --since or --base.

Precedence

• The range flags on the command line beat the config since, which applies only to a full scan.
• --config PATH beats the workspace .refquiem.toml.
• The default excludes and the exclude globs both apply.
• --package NAME reads mentions only from the files of that workspace member. The name must match a member or the run fails with exit 2, while the scan itself still covers the whole workspace.

allow entries

An entry suppresses a group when it spells the group's full path or ends it at a :: boundary, so allow = ["old_item"] suppresses every removed item whose path is old_item or ends in ::old_item. A bare entry that holds no :: additionally drops the mentions of that identifier, so it also covers a mention whose text is the bare name and whose target path the entry does not spell.

Suppression markers

refquiem: allow(name1, name2) in a Rust line comment, block doc comment or Markdown HTML comment suppresses the mentions it names. In Markdown files, marker text inside a code span or fenced block has no suppression effect.

• The names are comma-separated, and each is an item path or a manifest entry name whose :: segments may hold letters, digits, _, -, + and ..
• A marker suppresses a mention in the same file on its own line or the following line.
• A marker that holds anything but names and paths is ignored.
• A marker that suppressed nothing is reported as file:line:column refquiem: allow(name) suppresses nothing and makes the run unclean.

Exit codes

Code	Meaning
0	no findings and no unused markers, or --no-fail
1	at least one finding or unused marker
2	an error, printed to stderr as refquiem: message followed by each cause

The skipped-dependency warnings never change the exit code.

Output

The human report goes to stdout. --markdown replaces it with the Markdown job summary, and --json with one JSON object, which also skips the --github output. --markdown cannot be combined with --json or --github. --github appends workflow annotations after the human report and appends the job summary to $GITHUB_STEP_SUMMARY when the variable is set.

• The annotations are one per mention and per unused marker at ::error level, and one per skipped dependency at ::warning level. --no-fail lowers the findings to ::warning, and the skipped-dependency warnings stay ::warning.
• The JSON object holds base, groups with path, kind, member, removed_in, declared_at, suggestion, suggested_at, candidates, headline and mentions, where each mention holds file, line, column, text, context and replacement, plus skipped with dependency and reason, and unused_markers with file, line, column and name. base is the commit the range starts from. The removed_in of a group is the commit id or working_tree, its declared_at is the file and line where base declares the name, and its suggested_at is the file and line where the compared snapshot declares the suggestion. See Reports.

Parsed files and the manifests that locate dependency sources are cached at target/refquiem of the workspace, or at $CARGO_TARGET_DIR/refquiem under cargo. See History and cache.