.TH GIT-SLOP 1 "2026-08-05" "git-slop 0.9.2" "General Commands Manual"
.SH NAME
git-slop \- deterministic repository health and maintenance-pressure analysis
.SH SYNOPSIS
.B git-slop
.I command
.RI [ options ]
.br
.B git slop
.I command
.RI [ options ]
.SH DESCRIPTION
.B git-slop
is a native, local-first analyzer for tracked files in a Git repository.
It measures context cost and maintenance pressure, adds structural and
operational evidence, and writes machine-readable and human-readable reports.
Scoring does not require a hosted API or model provider.
.PP
When the executable is on
.BR PATH ,
Git can run it as
.BR "git slop" .
.SH COMMANDS
.TP
.B init
Scaffold
.BR .slop/config.yaml ,
.BR .slop/.gitignore ,
and generated-state directories. Use
.B --force
to overwrite generated config files.
.TP
.B find
Analyze tracked files and local Git history. Write
.BR report.json ,
.BR report.yaml ,
.BR summary.md ,
and
.B health.md
to
.B .slop/latest/
and a timestamped directory under
.BR .slop/runs/ .
.TP
.B show
Show one file or folder from an existing report.
The positional argument is a repository-relative path.
Options are
.BI --report " path"
and
.BI --format " text|json" .
.TP
.B explain
Explain a selected file, folder, relationship, cluster, or top-N action-queue
entries. Select with
.BI --path " path" ,
.BI --relationship " id" ,
.BI --cluster " id" ,
or
.BI --top " count" .
With no selector, the top five entries are used.
Additional options are
.BI --report " path" ,
.BI --format " text|json" ,
and
.BI --prompt-pack " directory" .
.TP
.B plan
Propose bounded maintenance slices from existing evidence.
Exactly one of
.BI --path " path" ,
.BI --relationship " id" ,
or
.BI --cluster " id"
is required.
Additional options are
.BI --report " path" ,
.BI --max-slices " count" ,
.BI --format " text|json" ,
and
.BI --prompt-pack " directory" .
.TP
.B check
Evaluate existing file records against stable detector thresholds.
Options are
.BI --report " path" ,
.BI --fail-on-context-band " compact|healthy|warning|critical" ,
and
.BI --fail-on-slop-band " low|moderate|high|critical" .
Overlays and health rollups do not affect this gate.
.TP
.B compare
Compare two existing schema-4 reports without rerunning the detector.
.BI --base " path"
and
.BI --head " path"
are required.
Optional arguments are
.BI --top " count"
and
.BI --format " text|json" .
.TP
.B sarif
Export action-queue findings from an existing schema-4 report as SARIF 2.1.0.
Options are
.BI --report " path" ,
.BI --top " count" ,
and
.BI --output " path" .
Without
.B --output
the document is written to standard output.
.TP
.B health
Render additive repository-health evidence from an existing schema-4 report.
Options are
.BI --report " path" ,
.BI --format " markdown|github|json" ,
and
.BI --max-annotations " count" .
The default format is
.B markdown
and the default annotation cap is 10.
All formats write to standard output and do not rewrite
.BR .slop/latest/health.md .
The GitHub format emits bounded workflow-command annotations.
Findings are advisory: successful rendering returns 0 even when findings are
present. Use
.B check
to enforce stable detector thresholds.
.TP
.B version
Print
.B git-slop
and the installed package version.
.TP
.B build-info
Print schema-1 JSON containing the package version and source-build provenance.
The only format is
.BR "--format json" .
Verified release builds report the full source revision and
.BR "source_dirty: false" ;
unverifiable local source identity is represented by nullable fields.
.SH REPORT FILES
Unless overridden with
.BR --report ,
report-consuming commands read
.BR .slop/latest/report.json .
The current machine contract is report schema 4.
.PP
.B summary.md
contains detailed detector and overlay evidence.
.B health.md
contains status bands, token distributions, review candidates, watchlists,
actionable findings, and profile/language rollups for humans and CI.
.SH EXAMPLES
.TP
.B git slop init
Create repository-local config and generated-state boundaries.
.TP
.B git slop find
Generate a schema-4 report bundle for the current repository.
.TP
.B git slop health
Render the repository-health dashboard from the latest report to standard
output without rewriting
.BR health.md .
.TP
.B git slop health --format github --max-annotations 10
Emit at most ten GitHub workflow annotations.
.TP
.B git slop explain --path src/report.rs
Explain stable cost and additive evidence for one path.
.TP
.B git slop plan --path src --max-slices 3
Propose up to three bounded maintenance slices.
.TP
.B git slop check --fail-on-context-band warning
Fail when any file is at or above the warning context band.
.TP
.B git slop compare --base old.json --head new.json
Compare two previously generated reports.
.TP
.B git slop build-info --format json
Print the package version, full source revision when known, and source-dirty
state as schema-1 JSON.
.SH EXIT STATUS
.B health
returns 0 after successful rendering even when findings are present. Invalid
input or a runtime failure returns a nonzero status.
.PP
.B check
returns 0 when no file meets either threshold, 1 when findings meet a
threshold, and 2 for invalid report or command input.
Other commands return 0 on success and a nonzero status for invalid input or
runtime failure.
.SH FILES
.TP
.B .slop/config.yaml
Repository-owned config schema 2.
.TP
.B .slop/.gitignore
Ignore rules for routine generated state.
.TP
.B .slop/latest/
Latest four-file report bundle.
.TP
.B .slop/runs/
Timestamped report bundles.
.TP
.B .slop/cache/
Disposable generated cache state.
.SH BOUNDARIES
Git Slop does not rewrite code, mutate GitHub, invoke a hosted model, or treat
findings as correctness proofs. Stable costs, overlays, and health projections
remain separate.
.SH SEE ALSO
.BR git (1)