macfilesizing

A fast, structured command-line utility designed for disk space analysis and storage reclamation on macOS and Linux systems.

---

Overview

Storage management tools on Unix-like platforms typically force a trade-off between speed, legibility, and granularity:

• Built-in graphical utilities (such as macOS Storage Management) categorize vast portions of storage under opaque categories like "System Data", obscuring actionable file paths.
• Traditional command-line tools like du require complex piping (e.g., du -sh * | sort -hr) to order results, lack real-time feedback during large tree traversals, and fail abruptly on permission-restricted paths unless explicitly suppressed.
• High-level interactive terminal disk usage analyzers (e.g., ncdu) require full indexation passes before presenting interactive state and are not inherently optimized for scriptable, automated text reporting.

macfilesizing provides an immediate, deterministic solution: it traverses directories recursively or at the top level, dynamically computes entity weights, handles system-level permission barriers gracefully, and outputs items in strict descending order with standardized human-readable units.

---

Key Features

• Automated Descending Sort: Evaluates and orders all discovered paths strictly by total disk usage.
• Recursive Subtree Traversal: Configurable deep-scan mode (--tree) to detect deeply nested build caches and orphaned data.
• Dynamic Progress Tracking: Integrated progress updates via tqdm to maintain visibility over high-latency I/O operations.
• Resilient I/O and Permission Handling: Silently isolates and skips permission-denied directories to ensure scans run to completion without interruption.
• Text-Based Audit Export: Direct reporting pipeline (--report) designed for headless servers, backup verification, and automated maintenance workflows.
• Zero Heavyweight Dependencies: Lightweight implementation requiring only Python 3.6+ and standard CLI modules.

---

Installation

Homebrew (macOS)

For macOS systems, installation via Homebrew is the supported method:

brew tap jaccon/tap
brew install macfilesizing

This provisions macfilesizing directly into your system $PATH within an isolated execution environment.

Pip

Install the package directly from GitHub via pip:

pip install git+https://github.com/jaccon/macfilesizing.git

Manual Installation

For local development or environments without package managers:

git clone https://github.com/jaccon/macfilesizing.git
cd macfilesizing
pip install -r requirements.txt
chmod +x macFileSizing.py

---

Usage

Command-Line Interface

macfilesizing --source <directory_path> [options]

Options

---

Examples

1. Shallow Scan of Current Directory

Evaluates the direct children of the specified path:

macfilesizing --source ~/Downloads

Sample output:

Analyzing directory: /Users/username/Downloads
Please wait, calculating sizes...

Type   Size         Name
--------------------------------------------------------------------------------
DIR    4.12 GB      Xcode_Old_Simulators
FILE   1.45 GB      ubuntu-24.04-desktop-amd64.iso
DIR    650.30 MB    raw_footage
FILE   210.15 MB    archive.tar.gz
FILE   45.10 MB     dataset.csv
--------------------------------------------------------------------------------
Total: 6.47 GB
Items found: 5

2. Recursive System and Project Audits

Perform a full tree traversal of development workspaces and output the summary to a persistent file:

macfilesizing --source ~/Projects --tree --report ~/storage_audit.txt

3. Server Maintenance Routine

Target system directories requiring elevated privileges:

sudo macfilesizing --source /var/log --tree --report /var/log/disk_usage_summary.txt

4. Automated Cron Execution

Configure weekly disk space monitoring for multi-user or build server environments:

0 2 * * 0 /usr/local/bin/macfilesizing --source /home --tree --report /var/log/audit/disk_$(date +\%Y\%m\%d).log

---

Output Format Specification

Console Output

Standard output is formatted into fixed-width columns:

• Type: Indicates entry type (DIR for directories, FILE for individual files).
• Size: Dynamic byte conversion using standard binary multiples (B, KB, MB, GB, TB, PB).
• Name / Path: Entry identifier (relative path when invoked with --tree).
• Total: Aggregate disk space consumed by all listed entries.
• Items found: Cardinality of all cataloged filesystem nodes.

Generated Reports

Reports generated via --report prepend execution metadata and timestamps, facilitating diffing across multiple audit cycles:

File Sizing Report
Generated: 2026-09-13 10:15:30
================================================================================

Analyzing directory: /Users/username/Documents
Mode: Recursive (tree mode)

Type   Size         Path
--------------------------------------------------------------------------------
DIR    2.45 GB      Projects/legacy-client-portal
FILE   856.32 MB    Presentations/annual-summit.pdf
DIR    543.21 MB    Databases/local-mysql-dump
FILE   234.56 MB    Archives/contracts-2024.zip
--------------------------------------------------------------------------------
Total: 4.08 GB
Items found: 842

---

Technical Specifications

• Runtime Compatibility: Python 3.6 and later.
• Operating Systems: macOS 10.13+, Linux (Ubuntu, Debian, Fedora, CentOS, Arch).
• Core Dependencies: tqdm (console rendering and progress metrics).

---

Troubleshooting

---

Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/improvement).
3. Commit your changes with clear, structured messages (git commit -m 'Implement path filtering').
4. Push to your branch (git push origin feature/improvement).
5. Open a Pull Request detailing the problem solved and test coverage added.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

Author

Developed by Jaccon (GitHub).