# How to Configure Mole's Protected Directories: A Complete Guide to the Whitelist System

> Learn to configure Mole's protected directories using the whitelist system. Secure your files from accidental deletion by mastering this essential feature. Protect your data today.

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

---

**Mole protects directories from accidental deletion by consulting a whitelist stored in `~/.config/mole/whitelist`, which is checked by the `is_path_whitelisted()` function before any removal operation.**

Mole is a macOS cleanup utility that safeguards system-critical folders and user data through a robust whitelist mechanism. Understanding how to configure these protected directories ensures you can safely clean caches and temporary files without risking important data.

## How Mole's Directory Protection Works

Mole implements a three-tier protection system: default hard-coded patterns, user-editable configuration files, and runtime validation functions.

### Default Protection Patterns

The built-in safeguards are defined in [`lib/core/base.sh`](https://github.com/tw93/Mole/blob/main/lib/core/base.sh) as the `DEFAULT_WHITELIST_PATTERNS` array (lines 85-101). This serves as a fallback when no user configuration exists, protecting critical system directories such as caches, model data, and system folders.

### User-Configurable Whitelist Files

Mole maintains separate whitelist files for different operations:

- **`~/.config/mole/whitelist`** – Used by standard `mo clean` operations
- **`~/.config/mole/whitelist_optimize`** – Used exclusively by `mo optimize` commands

These paths are defined in [`lib/manage/whitelist.sh`](https://github.com/tw93/Mole/blob/main/lib/manage/whitelist.sh) lines 12-15 as `WHITELIST_CONFIG_CLEAN` and `WHITELIST_CONFIG_OPTIMIZE`.

### Runtime Loading and Validation

The `load_whitelist()` function in [`lib/manage/whitelist.sh`](https://github.com/tw93/Mole/blob/main/lib/manage/whitelist.sh) (lines 82-118) reads the whitelist file into the runtime array `CURRENT_WHITELIST_PATTERNS`. If a legacy file `~/.config/mole/whitelist_checks` exists, it automatically migrates the content to the new location.

Before any deletion, `is_path_whitelisted()` (lines 44-60) performs an exact string match against `CURRENT_WHITELIST_PATTERNS`. Notably, **Mole does not expand glob patterns**—it compares the fully expanded path against stored patterns exactly, preventing unintended matches and security risks.

## Where to Configure Protected Directories

The configuration depends on the operation mode:

| File Path | Purpose | Source Reference |
|-----------|---------|------------------|
| `~/.config/mole/whitelist` | Standard clean operations | [`lib/manage/whitelist.sh`](https://github.com/tw93/Mole/blob/main/lib/manage/whitelist.sh) lines 12-13 |
| `~/.config/mole/whitelist_optimize` | Optimization-specific skips | [`lib/manage/whitelist.sh`](https://github.com/tw93/Mole/blob/main/lib/manage/whitelist.sh) lines 14-15 |
| [`lib/core/base.sh`](https://github.com/tw93/Mole/blob/main/lib/core/base.sh) | Hard-coded defaults | Lines 85-101 (`DEFAULT_WHITELIST_PATTERNS`) |

## How to Add or Remove Protected Directories

Mole offers two methods for modifying the whitelist: direct file editing and an interactive CLI.

### Method 1: Direct File Editing

Edit the whitelist file directly to add custom protected paths:

```bash

# Create or append to the whitelist file

cat >> "$HOME/.config/mole/whitelist" <<'EOF'

# Personal protected directories

$HOME/Documents/ImportantProject
$HOME/Development/CriticalRepo
EOF

```

Verify that Mole recognizes the new entries:

```bash
mo clean --dry-run | grep "ImportantProject"

```

The output should indicate the directory is "skipped (whitelist)".

### Method 2: Interactive CLI

Use the built-in interactive menu for visual management:

```bash

# Launch the whitelist manager for clean operations

mo clean --whitelist

```

For optimization-specific protections:

```bash
mo optimize --whitelist

```

Navigate using ↑/↓ keys, toggle selections with SPACE, and press ENTER to save. The CLI writes changes directly to the respective whitelist file in `~/.config/mole/`.

## Key Implementation Details

Understanding these technical specifics helps avoid configuration errors:

**Exact String Matching** – The `is_path_whitelisted()` function performs exact string comparisons (`[[ "$check_pattern" == "$existing_expanded" ]]`), not glob expansion. Patterns must match the full expanded path exactly.

**Separate Optimization Whitelist** – The `optimize` command uses a distinct whitelist (`whitelist_optimize`) that stores check names to skip (e.g., `check_brew_health`) rather than directory paths. This is loaded by [`bin/optimize.sh`](https://github.com/tw93/Mole/blob/main/bin/optimize.sh).

**Automatic Migration** – If `~/.config/mole/whitelist_checks` exists from an older version, `load_whitelist()` automatically migrates its contents to the new standard location.

**Core Clean Integration** – In [`bin/clean.sh`](https://github.com/tw93/Mole/blob/main/bin/clean.sh) (line 92), the whitelist is loaded into `WHITELIST_PATTERNS`, and line 386 calls `is_path_whitelisted` before executing any deletion.

## Summary

- **Primary whitelist location**: `~/.config/mole/whitelist` for standard clean operations, `~/.config/mole/whitelist_optimize` for optimization mode
- **Default patterns**: Defined in [`lib/core/base.sh`](https://github.com/tw93/Mole/blob/main/lib/core/base.sh) as `DEFAULT_WHITELIST_PATTERNS` (lines 85-101)
- **Configuration methods**: Direct file editing or interactive CLI via `mo clean --whitelist`
- **Matching behavior**: Exact string comparison only—no glob expansion performed by `is_path_whitelisted()` in [`lib/manage/whitelist.sh`](https://github.com/tw93/Mole/blob/main/lib/manage/whitelist.sh)
- **Runtime loading**: `load_whitelist()` in [`lib/manage/whitelist.sh`](https://github.com/tw93/Mole/blob/main/lib/manage/whitelist.sh) (lines 82-118) populates the `CURRENT_WHITELIST_PATTERNS` array used by [`bin/clean.sh`](https://github.com/tw93/Mole/blob/main/bin/clean.sh)

## Frequently Asked Questions

### Where is the default whitelist defined in the Mole source code?

The default whitelist patterns are defined in [`lib/core/base.sh`](https://github.com/tw93/Mole/blob/main/lib/core/base.sh) within the `DEFAULT_WHITELIST_PATTERNS` array (lines 85-101). These serve as fallback values when no user configuration exists at `~/.config/mole/whitelist`.

### Can I use wildcards or glob patterns in the whitelist file?

No. According to the `is_path_whitelisted()` implementation in [`lib/manage/whitelist.sh`](https://github.com/tw93/Mole/blob/main/lib/manage/whitelist.sh) (lines 44-60), Mole performs exact string matching only (`[[ "$check_pattern" == "$existing_expanded" ]]`). Glob expansion is intentionally disabled for security reasons to prevent unintended matches.

### What is the difference between `whitelist` and `whitelist_optimize`?

The `~/.config/mole/whitelist` file controls which directories are protected during standard `mo clean` operations, while `~/.config/mole/whitelist_optimize` stores check names to skip during `mo optimize` (such as `check_brew_health`). They are loaded by [`bin/clean.sh`](https://github.com/tw93/Mole/blob/main/bin/clean.sh) and [`bin/optimize.sh`](https://github.com/tw93/Mole/blob/main/bin/optimize.sh) respectively.

### How do I temporarily disable whitelist protection for a single run?

To bypass whitelist checks temporarily, you can run Mole with an empty whitelist file by setting the environment variable to `/dev/null`: `MOLE_WHITELIST_FILE="/dev/null" mo clean --dry-run`. Alternatively, for testing purposes, you can use the `--dry-run` flag to preview what would be deleted without actually removing anything, allowing you to verify whitelist behavior safely.