module Lapis::Docs::B_LAPIS_CLI_AND_TOOLCHAIN::F_CLEAN_AND_MAINTENANCE

Overview

Workspace Cleaning & Disk Reclamation

Comprehensive guide to cleaning build artifacts and reclaiming disk space with lapis clean, highlighting automated protections for nested git subprojects and runtime shared libraries.

Executive Summary & Key Topics

Topic	Method / Anchor	Description
Clean Operational Modes	`.topic_00_clean_modes`	Standard clean, shadow DLL pruning, full purge, and dry-run preview.
lapis clean: Options & Flags	`.topic_01_command_options`	Command-line syntax and option reference.
Subproject & Git Protection Invariants	`.topic_02_safety_guards`	How lapis clean protects checked-out repositories and critical runtime dependencies.
Sample Clean Outputs	`.topic_03_expected_output`	Terminal output during dry-run and shadow reclamation.

Related Guides & Source References

Clean Implementation: tools/lapis/src/commands/clean.cr
Live Spec: tools/lapis/spec/commands/clean_spec.cr

Defined in:

libgodot/docs/b_lapis_cli_and_toolchain/f_clean_and_maintenance.cr

Class Method Summary

.topic_00_clean_modes : Nil
Clean Operational Modes: Standard clean, shadow DLL pruning, full purge, and dry-run preview.
.topic_01_command_options : Nil
lapis clean: Options & Flags: Command-line syntax and option reference.
.topic_02_safety_guards : Nil
Subproject & Git Protection Invariants: How lapis clean protects checked-out repositories and critical runtime dependencies.
.topic_03_expected_output : Nil
Sample Clean Outputs: Terminal output during dry-run and shadow reclamation.

Class Method Detail

def self.topic_00_clean_modes : Nil #

Clean Operational Modes: Standard clean, shadow DLL pruning, full purge, and dry-run preview.

Key Topics & Information

Standard clean: lapis clean (removes compiled game/plugin binaries, keeps runtime DLLs)
Shadow pruning: lapis clean --shadows (prunes only temporary loaded DLLs and PDBs)
Dry-run preview: lapis clean --dry-run (computes files and bytes to reclaim without deleting)
Full purge: lapis clean --all (removes intermediate build caches, shadow DLLs, and test remnants)

def self.topic_01_command_options : Nil #

lapis clean: Options & Flags: Command-line syntax and option reference.

Usage:

lapis clean [options]

Options:

Option	Shorthand	Description
`--shadows`	`-s`	Prunes only stale Windows shadow DLLs (`_loaded_.dll/pdb`)
`--dry-run`	`-n`	Previews files and exact disk space to be freed without deleting
`--all`	`-a`	Comprehensive clean including build caches and intermediate files
`--docs`		Also removes generated `docs/` HTML manual
`-p, --project=DIR`		Target specific project directory (default: current directory)

def self.topic_02_safety_guards : Nil #

Subproject & Git Protection Invariants: How lapis clean protects checked-out repositories and critical runtime dependencies.

To prevent accidental data loss:

Subproject Repository Protection: clean_bin_dir inspects each folder inside bin/ and skips any directory containing .git or .gitkeep. Even if you check out a repository inside bin/ (e.g. bin/crshader), lapis clean will never delete it!
Runtime DLL Preservation: Core shared libraries (gc.dll, pcre2-8.dll, iconv-2.dll, libgodot.dll) are never deleted by standard clean.
Documentation Protection: The docs/ folder is preserved by default and is only removed if --docs or --all is explicitly passed.

def self.topic_03_expected_output : Nil #

Sample Clean Outputs: Terminal output during dry-run and shadow reclamation.

Running Shadow Pruning:

lapis clean --shadows

[Clean] Cleaning stale shadow DLLs (*_loaded_*) across workspace...
[Lapis] Shadow libraries cleaned successfully! Reclaimed 24.79 GB across 1727 file(s).

Running Dry-Run:

lapis clean --dry-run

[Clean:DryRun] Scanning workspace for removable artifacts...
  Candidate: bin/game.dll (28.45 MB)
  Candidate: bin/plugin.dll (14.20 MB)
[Clean:DryRun] Dry run complete: 2 file(s) would be removed, reclaiming 42.65 MB.