delphi-clean

Overview

delphi-clean is a PowerShell utility for Delphi developers to remove build artifacts, intermediate files, and IDE-generated clutter, with support for preview, validation, and CI workflows.

---

Running the Tool

If delphi-clean is on your PATH:

delphi-clean -Level standard

Otherwise, run it directly:

pwsh -File .\delphi-clean.ps1 -Level standard
# or
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\delphi-clean.ps1 -Level standard

PowerShell Compatibility

Runs on the widely available Windows PowerShell 5.1 (powershell.exe) and the newer PowerShell 7+ (pwsh).

---

Features

• Specify cleanup levels: basic, standard, deep via -Level
• CI-friendly output with optional -Json mode
• Optional structured output via -PassThru
• Supports the -WhatIf dry-run mode
• Add extra file patterns with -IncludeFilePattern
• Exclude directories by wildcard pattern with -ExcludeDirectoryPattern
• Send items to the recycle bin / trash instead of permanent deletion with -RecycleBin
• Use -OutputLevel to adjust how much detail is shown
• Check for cleanup artifacts without modifying files using -Check
• JSON configuration file hierarchy ($HOME, project-level, local override, -ConfigFile)
• Inspect the effective merged configuration with -ShowConfig
• Inject a CI-specific config file via -ConfigFile

---

Usage

Run delphi-clean from the current working directory, or specify a different root with -RootPath

Basic Usage

delphi-clean

---

-RootPath

Root path defaults to the current working directory (via Get-Location), or you can provide it explicitly.

Example:

delphi-clean -RootPath C:\code\my-project

---

-Level

Clean Levels

basic (default)

Safe cleanup of common transient files.

Includes:

• .dcu, .tmp, .bak, .identcache
• __history

---

standard

Removes build outputs and generated artifacts.

Includes everything in basic, plus:

• Compiled binaries (.exe, .bpl, etc.)
• Debug and release folders
• Intermediate files

---

deep

More aggressive cleanup

Includes everything in standard, plus:

• Backup files (*.~*)
• FinalBuilder related files (logs, breakpoint, lock)
• TestInsight custom settings

Examples:

delphi-clean -Level basic
delphi-clean -Level standard
delphi-clean -Level deep

See /docs/cleanup-levels.md for breakdown of what is included by default in each level

---

-WhatIf

Preview cleanup without making changes. (Dry Run Mode)

delphi-clean -WhatIf

Shows what would be deleted without making changes.

---

-Verbose

Extra output for debugging purposes

delphi-clean -Verbose

---

-PassThru

Structured Output: Returns objects describing each item processed.

delphi-clean -PassThru

---

-Json

Outputs a single JSON object to standard output. All other output (text, progress) is suppressed. Key fields include:

• Level, Root, Mode -- invocation metadata
• FilesFound, DirectoriesFound -- items discovered during scan
• FilesDeleted, DirectoriesDeleted -- items actually removed
• BytesFreed -- total bytes freed (or would-be freed in -WhatIf/-Check)
• DurationMs -- elapsed time in milliseconds
• Disposition (Permanent or Recycle Bin) and RecycleBin flag
• Items[] -- per-item records with Type, Path, Deleted, and Size (bytes)

delphi-clean -Json

See docs/json-output.md for the full field reference.

---

-IncludeFilePattern

Appends additional glob patterns to the level's built-in file list. Useful for project-specific artifacts not covered by the standard levels.

delphi-clean -Level basic -IncludeFilePattern '*.res'
delphi-clean -Level basic -IncludeFilePattern '*.res','*.mab'

---

-ExcludeDirectoryPattern

Skips any directory whose name matches one of the given wildcard patterns. Patterns are matched with -like so wildcards (*, ?) are supported.

Specific directories are excluded by default: .git, .vs, and .claude.

delphi-clean -ExcludeDirectoryPattern 'vendor*'
delphi-clean -ExcludeDirectoryPattern 'vendor*','assets'

---

-RecycleBin

Sends items to the platform trash instead of permanently deleting them.

Platform	Destination
Windows	Recycle Bin (Microsoft.VisualBasic.FileIO)
macOS	~/.Trash/
Linux	~/.local/share/Trash/ (FreeDesktop spec)

Combine with -WhatIf to preview which items would be recycled without making any changes.

delphi-clean -RecycleBin
delphi-clean -Level standard -RecycleBin

---

-OutputLevel

Use -OutputLevel to control how much information delphi-clean writes during execution or check mode.

Options

• detailed (default)

  Shows full output including headers, per-item actions (or matches in -Check), and summary totals.

• summary

  Suppresses per-item output and shows only high-level information and totals.

• quiet

  Suppresses all normal output. Only warnings and errors are displayed. Intended for automation scenarios where the exit code is the primary signal.

Behavior

• Applies to both normal cleanup runs and -Check mode
• Does not affect JSON output (-Json always returns structured data)
• Warnings and errors are never suppressed, even with quiet

Examples

Show full detail (default):

delphi-clean

Show only totals:

delphi-clean -OutputLevel summary

Silent run for CI:

delphi-clean -Level standard -OutputLevel quiet

Notes

• detailed is useful for interactive use and troubleshooting
• summary is ideal for large repositories to reduce noise
• quiet is best for scripts where only the exit code matters

-Check

Use -Check to audit a project folder without making any changes.

In check mode, delphi-clean performs a full scan using the selected cleanup level and reports any files or directories that would be removed during a normal run.

No files are deleted, moved, or modified.

delphi-clean -Check

Output controlled by -OutputLevel:

• detailed (default): lists matching items and summary
• summary: totals only
• quiet: no output (use exit code only)

Example: use in CI to validate a workspace

delphi-clean -Check -OutputLevel quiet
if ($LASTEXITCODE -ne 0) {
    throw "Repository contains build artifacts"
}

Example: view detailed list of matching files:

delphi-clean -Level deep -Check -OutputLevel detailed

Notes:

• -Check cannot be combined with -WhatIf
• -RecycleBin has no effect in check mode
• For a simulated run that shows what would be deleted during execution, use -WhatIf

Check vs WhatIf:

• Use -WhatIf to preview what a cleanup run would do
• Use -Check to determine whether cleanup is needed (with exit code support)

---

-ShowConfig

Displays the effective merged configuration that would be used for the current invocation, then exits without scanning or cleaning. No files are modified.

delphi-clean -ShowConfig
delphi-clean -ShowConfig -Json

The output lists every config file that was found and loaded, plus the final resolved value for each property (including built-in excluded directories and any CLI overrides already applied).

---

-ConfigFile

Injects an explicit JSON configuration file at the highest config priority (above project-level and local files, below command-line parameters). Useful in CI pipelines where the config lives outside the repository tree, or when testing a config before committing it.

delphi-clean -ConfigFile C:/ci/delphi-clean-ci.json -Level standard

The file uses the same JSON format as delphi-clean.json. See docs/configuration.md for the full key reference.

---

Configuration Files

delphi-clean supports optional JSON configuration files so you can encode per-project and per-user preferences without repeating them on the command line.

Config sources, from lowest to highest priority:

$HOME/delphi-clean.json          user-level defaults
  <RootPath>/delphi-clean.json   project-level (commit with the repo)
    <RootPath>/delphi-clean.local.json  local user overrides (add to .gitignore)
      -ConfigFile <path>                explicit file (e.g. for CI)
        command-line parameters         highest priority

Scalars override -- the highest-priority source wins. Arrays append -- items from all sources are combined; duplicates are removed.

Example delphi-clean.json (project-level):

{
  "level": "standard",
  "outputLevel": "summary",
  "includeFilePattern": ["*.res"],
  "excludeDirectoryPattern": ["assets"],
  "searchParentFolders": false
}

See docs/configuration.md for the full reference, including upward traversal (searchParentFolders) and monorepo patterns.

---

Exit Codes

  0 = success: cleanup completed, WhatIf completed, or Check found no artifacts
  1 = dirty: check mode found artifacts (validation failure)
  2 = partial: the script reached the removal phase but at least one item could not
               be deleted or recycled; 
               Note: successfully removed items are not rolled back
  3 = fatal:   unhandled exception before or during the scan phase - bad root path,
               unsupported platform for -RecycleBin, scan error, etc.

---

Maturity

This repository is currently incubator and is under active development. It will graduate to stable once:

• At least one downstream consumer exists.

Until graduation, breaking changes may occur

---

Continuous-Delphi

This tool is part of the Continuous-Delphi ecosystem, focused on strengthening Delphi’s continued success