When should I use disk-space-mapper?

disk-space-mapper is useful in the following scenarios: • Storage Auditing: Perform a deep scan of directory trees to visualize disk space distribution and identify which projects or datasets are consuming the most resources. • Automated Cleanup: Identify directories that haven't been modified for a specific period (e.g., 180+ days) and exceed a size threshold to reclaim disk space. • System Maintenance Reporting: Generate pipe-delimited reports of filesystem usage that can be easily parsed, archived, or shared for infrastructure audits. • Activity Monitoring: Track recent filesystem changes by sorting directories by their last modification date to identify active work zones or unexpected growth.

disk-space-mapper

from tonytamsf

Analyze disk usage across directories, identify large/old directories, and generate storage reports. Use when you need to find directories consuming disk space, identify candidates for cleanup (directories older than X days AND larger than Y MB), sort results by size, or generate disk usage reports. Supports filtering by age and size, automatic sorting by disk space, and file-based report generation.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 28, 2025

When & Why to Use This Skill

Disk Space Mapper is a specialized utility for disk usage analysis and storage optimization. It helps users identify large directories, locate obsolete data based on age, and generate structured storage reports. By automating the process of finding 'storage hogs' and cleanup candidates, it simplifies filesystem maintenance and capacity planning for developers and system administrators.

Use Cases

Storage Auditing: Perform a deep scan of directory trees to visualize disk space distribution and identify which projects or datasets are consuming the most resources.
Automated Cleanup: Identify directories that haven't been modified for a specific period (e.g., 180+ days) and exceed a size threshold to reclaim disk space.
System Maintenance Reporting: Generate pipe-delimited reports of filesystem usage that can be easily parsed, archived, or shared for infrastructure audits.
Activity Monitoring: Track recent filesystem changes by sorting directories by their last modification date to identify active work zones or unexpected growth.

name	disk-space-mapper
description	Analyze disk usage across directories, identify large/old directories, and generate storage reports. Use when you need to find directories consuming disk space, identify candidates for cleanup (directories older than X days AND larger than Y MB), sort results by size, or generate disk usage reports. Supports filtering by age and size, automatic sorting by disk space, and file-based report generation.

name

disk-space-mapper

description

Disk Space Mapper

Overview

Quickly analyze disk usage across your filesystem, identify space hogs, and find old directories taking up storage. Perfect for cleanup projects, storage audits, and identifying which projects are consuming the most disk space.

Quick Start

Analyze a directory to see disk usage sorted by size:

python3 analyze_disk.py -d /path/to/analyze

Find old (>180 days) and large (>20MB) directories:

python3 analyze_disk.py -d /path/to/analyze -m 180 -s 20 -o report.txt

Common Tasks

1. Storage Audit

See what's consuming disk space in a directory tree:

python3 analyze_disk.py -d /Users/tonytam/git

Results automatically sort by size (largest first), showing:

Directory path
Size in MB
Last modification date
Days since last change

2. Find Cleanup Candidates

Identify directories not touched in 6 months that are larger than 20 MB:

python3 analyze_disk.py -d /Users/tonytam/git -m 180 -s 20 -o candidates.txt

3. Identify Recent Changes

See active directories (modified recently, largest first):

python3 analyze_disk.py -d /active/projects

Look for low "Days Since Change" values.

4. Threshold Filtering

Find anything over 100 MB:

python3 analyze_disk.py -d /data -s 100

Or anything older than 1 year:

python3 analyze_disk.py -d /archive -m 365

Available Scripts

Python Version (Recommended)

File: scripts/analyze_disk.py

Full-featured Python implementation. Use this for most tasks.

Options:

-d, --dir DIR - Base directory to analyze
-m, --min-days DAYS - Filter: only dirs older than N days
-s, --min-size SIZE_MB - Filter: only dirs larger than N MB
-o, --output FILE - Save results to file

Example:

python3 analyze_disk.py -d /git -m 180 -s 20 -o old_large.txt

Bash Version

File: scripts/analyze_disk.sh

Lightweight shell script using standard Unix tools (du, stat, find).

Options: Same as Python version with - prefix

Example:

./analyze_disk.sh -d /git -m 180 -s 20 -o old_large.txt

Output Format

Results are pipe-delimited (easy to parse or import):

Directory|Size (MB)|Last Modified|Days Since Change
==================================================
/path/to/large_dir|554 MB|Feb 23 13:34:56 2025|307 days
/path/to/medium_dir|242 MB|Mar 28 15:34:02 2025|274 days
/path/to/small_dir|37 MB|Dec  2 08:05:07 2023|756 days

Always sorted by size (largest first).

Reference Materials

For detailed usage examples, filtering patterns, and scenario-based workflows, see usage_guide.md.

Tips

No filters: Run without -m or -s to see all directories
Always sorted: Output automatically sorts by size (largest first)
Safe: Read-only analysis, no files are deleted
Fast: Most directory trees scan in under 30 seconds
Flexible: Use with grep, cut, or other Unix tools to further process results