# How to Customize Mole's Cleanup Targets: A Complete Guide

> Learn how to customize Mole's cleanup targets by modifying MOLE_PURGE_TARGETS or using mo purge --paths. Take full control of what and where Mole purges.

- Repository: [Tw93/Mole](https://github.com/tw93/Mole)
- Tags: how-to-guide
- Published: 2026-03-20

---

**Customize Mole's cleanup targets by editing the `MOLE_PURGE_TARGETS` array in [`lib/clean/purge_shared.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/purge_shared.sh) for *what* gets deleted, or use `mo purge --paths` to configure *where* Mole searches for those targets.**

Mole is a fast, Rust-based CLI tool for cleaning up development environments. When you run `mo purge`, it hunts for heavy build artifacts across your filesystem. To effectively customize Mole's cleanup targets, you need to understand its two-layer architecture: the static target definitions (what gets deleted) and the configurable search paths (where to look).

## Understanding Mole's Cleanup Architecture

Mole separates the cleanup logic into two distinct layers that you can customize independently:

| Layer | Purpose | Configuration Location |
|-------|---------|------------------------|
| **Target Definitions** | The list of directory names (e.g., `node_modules`, `target`, `dist`) that Mole identifies as deletable artifacts | [`lib/clean/purge_shared.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/purge_shared.sh) – `MOLE_PURGE_TARGETS` array |
| **Search Paths** | The directories where Mole recursively searches for those target folders | `~/.config/mole/purge_paths` (managed via `mo purge --paths`) |

## Customizing What Gets Cleaned (The Targets)

The `MOLE_PURGE_TARGETS` array in [`lib/clean/purge_shared.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/purge_shared.sh) defines the master list of folder names that `mo purge` will attempt to remove. By default, this includes common build artifacts like `node_modules`, `target` (Rust/Maven), `build` (Gradle), and `dist`.

### Editing the Target Array

To modify what gets deleted, locate the `MOLE_PURGE_TARGETS` definition in [`lib/clean/purge_shared.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/purge_shared.sh):

```bash
readonly MOLE_PURGE_TARGETS=(
    "node_modules"
    "target"        # Rust, Maven

    "build"         # Gradle, various

    "dist"          # JS builds

    "venv"          # Python

    ".venv"
    ".pytest_cache"
    # … additional targets …

)

```

**To add a target**, append a new quoted string to the array. **To remove a target**, delete its line from the array.

### Making Changes Permanent

Because `MOLE_PURGE_TARGETS` is declared as `readonly` at runtime, you must modify the source file before the script is sourced. For permanent changes:

1. Fork or clone the `tw93/Mole` repository
2. Edit [`lib/clean/purge_shared.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/purge_shared.sh) to customize your `MOLE_PURGE_TARGETS`
3. Reinstall Mole from your fork using the standard install script

## Customizing Where Mole Searches (The Paths)

You control which directories Mole scans for cleanup targets without modifying source code. Mole uses a configuration file at `~/.config/mole/purge_paths` to store user-defined search paths.

### Using the Interactive Configurator

The simplest way to customize search paths is using the built-in command:

```bash
mo purge --paths

```

This opens your default editor (configured via `$EDITOR`) with the `purge_paths` file, or creates it if it doesn't exist. Each line should contain one absolute path. The file supports tilde expansion (`~` becomes `$HOME`).

### Manual File Editing

You can also edit the file directly:

```bash
nano ~/.config/mole/purge_paths

```

The expected format is one absolute path per line:

```text

# Mole Purge Paths - Auto-discovered project directories

# Edit this file to customize, or run: mo purge --paths

# Add one path per line (supports ~ for home directory)

~/Projects
~/Work
/Volumes/ExternalDrive/Repos

```

After saving, running `mo purge` will scan only these directories (and their subdirectories) for the targets defined in `MOLE_PURGE_TARGETS`.

## Protecting Specific Folders with Whitelisting

If you need to ensure specific directories are never deleted—even if they match target names like `node_modules`—use the whitelist feature.

Add a path to the whitelist using:

```bash
mo clean --whitelist

```

This interactively adds paths to `~/.config/mole/whitelist`. The `is_path_whitelisted` helper function checks this list before any deletion operation, protecting whitelisted directories from both `mo clean` and `mo purge` operations.

## Complete Workflow Example

Here is a typical customization workflow combining all three methods:

```bash

# 1. Edit the target list (optional) – remove "vendor" if you never want to delete Composer packages

nano "$(git rev-parse --show-toplevel)/lib/clean/purge_shared.sh"

# 2. Define where Mole should look for projects

mo purge --paths      # edit ~/.config/mole/purge_paths

# 3. Whitelist a folder you never want removed

mo clean --whitelist  # interactively add e.g. ~/Projects/important/node_modules

# 4. Run a dry-run to see what will be removed

mo purge --dry-run

```

## Technical Implementation Details

According to the `tw93/Mole` source code, the cleanup customization is implemented through four key mechanisms:

1. **Loading defaults** – [`project.sh`](https://github.com/tw93/Mole/blob/main/project.sh) sources [`purge_shared.sh`](https://github.com/tw93/Mole/blob/main/purge_shared.sh) and copies `MOLE_PURGE_TARGETS` into its own `PURGE_TARGETS` variable.

2. **Resolving scan paths** – The `load_purge_config` function reads `~/.config/mole/purge_paths` via `mole_purge_read_paths_config` in [`purge_shared.sh`](https://github.com/tw93/Mole/blob/main/purge_shared.sh). If the file is empty, Mole falls back to auto-discovery based on `MOLE_PURGE_DEFAULT_SEARCH_PATHS`.

3. **Scanning** – When `mo purge` executes, `clean_project_caches` iterates over `PURGE_SEARCH_PATHS`, recursively walks each tree, and identifies directories matching names in `PURGE_TARGETS`. Directories older than `MIN_AGE_DAYS` (default 7) are queued for deletion.

4. **Whitelist protection** – The `is_path_whitelisted` helper checks against `~/.config/mole/whitelist` before any deletion, ensuring protected directories survive cleanup operations.

## Summary

- **Edit `MOLE_PURGE_TARGETS`** in [`lib/clean/purge_shared.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/purge_shared.sh) to change *what* folder names are considered purge‑able (requires source modification).
- **Use `mo purge --paths`** to configure *where* Mole searches for those targets via `~/.config/mole/purge_paths` (no source code changes needed).
- **Run `mo clean --whitelist`** to protect specific directories from deletion by adding them to `~/.config/mole/whitelist`.
- **Test changes** with `mo purge --dry-run` before executing destructive operations.

## Frequently Asked Questions

### How do I add a custom folder name like `.cache` to Mole's cleanup list?

To add a custom target like `.cache`, you must edit the `MOLE_PURGE_TARGETS` array in [`lib/clean/purge_shared.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/purge_shared.sh) before installing or running Mole. Add `"cache"` or `.cache` to the array, then reinstall Mole from your modified source. There is currently no runtime configuration for adding new target names without modifying the source code.

### Can I exclude specific directories from being scanned without whitelisting them?

Yes. Instead of using the whitelist (which prevents deletion of specific folders), you can control *which* top-level directories Mole scans by editing `~/.config/mole/purge_paths`. Remove any paths you don't want scanned from this file. Mole will only recurse into directories explicitly listed in this configuration file or auto-discovered if the file is empty.

### What happens if I delete `~/.config/mole/purge_paths`?

If you delete the `purge_paths` file, Mole will fall back to its default behavior. According to the implementation in [`lib/clean/project.sh`](https://github.com/tw93/Mole/blob/main/lib/clean/project.sh), when the configuration file is missing or empty, Mole uses `MOLE_PURGE_DEFAULT_SEARCH_PATHS` defined in [`purge_shared.sh`](https://github.com/tw93/Mole/blob/main/purge_shared.sh) to auto-discover common development directories under your `$HOME` folder.

### How does the whitelist interact with the target list?

The whitelist acts as a final safety layer. When `mo purge` or `mo clean` runs, Mole first identifies directories matching the `MOLE_PURGE_TARGETS` names. Before deleting any directory, the `is_path_whitelisted` function checks if the path exists in `~/.config/mole/whitelist`. If whitelisted, the directory is skipped regardless of whether it matches a target name or how old it is.