Twelve of thirteen stale docs were kept alive only by each other

Description and use

A large set of stale Markdown files was safely moved to a trash folder using the mdsweep tool, which classifies files by age and inbound references.

Problem

A large number of markdown documentation files in many repos were old and potentially unnecessary, but simple age‑based deletion would risk removing files that were still referenced within the repo.

Outcome

The tool identified 687 active, 172 stale, and 176 orphan markdown files across 36 repos. Orphan files were safely moved to a trash directory, preserving a manifest for restoration. The approach avoided accidental deletion of referenced files while cleaning up truly unused documentation.

Workflow

• 1. Scan repo for markdown files and collect metadata (age, inbound links).
• 2. Classify each file: if age <= threshold → active; else if refs > 0 → stale; else → orphan.
• 3. For orphan files, move them to .mdsweep/trash/<timestamp>/ and record original path in a manifest.
• 4. Optionally run the tool with --apply to perform the move; otherwise review the report.
• 5. Use mdsweep undo to restore files if needed.
• 6. Periodically run the scan to keep the repo tidy.

Evidence

Across those 36 repos: 687 active, 172 stale, 176 orphan.

Source

Orphans get moved rather than deleted. fs.renameSync puts them in .mdsweep/trash/<timestamp>/ next to a manifest that records every original path.

Source