Mac Storage Manager is a shell script that helps you reclaim disk space by identifying and managing large applications on your system. Originally built for macOS, this new version has been refactored to work on both macOS and Linux. It calculates the size of installed applications (including Homebrew formulas and casks on macOS) and provides an interactive interface for safely deleting applications along with their associated files.
- Features
- Log File
- Homebrew
- Watch the Demo
- Continuous Integration
- How to Use
- Known Limitations and Common Issues
- Dependencies
- What Exactly is Deleted
- Warning
- Connect with me
- License
-
Cross-Platform Support:
- macOS: Scans
/Applicationsand~/Applicationsfor.appbundles. - Linux: Scans
/usr/share/applicationsand~/.local/share/applicationsfor.desktopfiles.
- macOS: Scans
-
Size Calculation:
- Calculates sizes for Homebrew formulas and casks (macOS only).
- Scans standard application directories.
- Optionally performs a comprehensive search using
sudo find.
-
Interactive Deletion:
- Graphical dialogs using whiptail for selecting applications to delete.
- Prompts for confirmation before deleting main files and associated files.
-
Selective Associated File Deletion:
- macOS: Offers to remove Application Support, Preferences, Caches, Logs, and Saved Application State.
- Linux: Offers to remove Application Data, Configuration, Cache, and Log files based on XDG directories.
-
Progress and Audio Feedback:
- Displays progress bars during long-running tasks.
- Plays sound effects for key actions (using
afplayon macOS andpaplayon Linux).
-
Logging:
- Records errors and detailed process logs in
application_size_checker.log.
- Records errors and detailed process logs in
The script creates the log file application_size_checker.log, which records important events and error messages. In addition to error and debug messages, the log file contains the following information:
-
Timestamps:
- Script Start and End: Timestamps are explicitly logged at the beginning and the end of the script using the
datecommand.
- Script Start and End: Timestamps are explicitly logged at the beginning and the end of the script using the
-
Debug Information:
- The sound path used by the script is logged at the start (e.g.,
DEBUG: SOUND_PATH=...). - Outputs of commands like
ls -l(for instance, the contents of the sound directory) are recorded.
- The sound path used by the script is logged at the start (e.g.,
-
Error Messages and Warnings:
- Detailed logs are kept for errors when accessing files or deleting applications (both in the main script and when removing associated files).
- Notifications for failed or canceled sudo password prompts, as well as any unsuccessful Homebrew operations (e.g., during uninstallation), are logged.
-
Progress Updates:
- During long-running operations (e.g., searching for applications, calculating sizes, or deleting files), progress updates and the corresponding process steps (e.g., "Deleting...", "Running 'sudo find'...") are recorded in the log file.
This comprehensive logging provides a complete overview of the script's execution and helps you pinpoint where the process may have failed in case any issues occur.
For macOS users, a dedicated Homebrew tap is provided specifically for Mac Storage Manager. This tap ensures that the Homebrew formula is always up-to-date and error-free. You can check it out at the following link:
NarekMosisian/homebrew-mac-storage-manager
The tap also includes its own CI configuration to ensure continuous updates and error-free operation of the formula.
Tip: Hold down Ctrl (Windows/Linux) or Cmd (Mac) and click the image to open the video in a new tab.
Click the image to watch the demo video on YouTube.
This project uses GitHub Actions for continuous integration. Every push and pull request to the main branch triggers a workflow that:
- Updates Homebrew (ignoring non-critical warnings)
- Installs dependencies (jq, newt)
- Taps the external Homebrew repository (NarekMosisian/mac-storage-manager)
- Installs the
mac-storage-managerformula - Runs tests (using
brew test mac-storage-manager) - Performs a strict audit of the formula
You can view the current CI status using the badge at the top.
Clone the repository to your local machine:
git clone https://github.com/NarekMosisian/mac-storage-manager.gitNavigate to the cloned directory and make the script executable by running:
chmod +x ./application_size_checker.shThe script relies on several tools. Install them as follows:
- macOS (using Homebrew):
brew install jq newt- Linux (using your package manager or Linuxbrew):
# On Debian/Ubuntu-based systems:
sudo apt-get update
sudo apt-get install jq newt paplay
# Alternatively, if using Linuxbrew:
brew install jq newtNote: On macOS, afplay is used for audio, while on Linux paplay is used.
jq: Parses JSON output from system commands.
newt: Provides terminal-based GUI dialogs (for interactive selection and progress bars).
Launch the script by executing:
./application_size_checker.shOr, explicitly with zsh:
zsh ./application_size_checker.shNote: The script uses zsh. Ensure that zsh is installed and set as your default shell, or run the script explicitly with zsh:
zsh ./application_size_checker.shDuring the script's execution, you will be prompted with the following option:
Include sudo find: This step searches for all applications across the system but may take a long time to complete.
Once the script has gathered the sizes of all applications, a graphical interface will appear, allowing you to select the applications you wish to delete. After selection, the script will:
Prompt for confirmation before deleting each application and its associated files.
Display the list of files and directories that will be removed for each application.
Prompt you for each category of associated files (Application Support, Preferences, Caches, Logs, Saved Application State) whether you want to delete them.
Optionally delete any additional files found via sudo find that are associated with the application.
- Performance: Searching the entire system with sudo find can be time-consuming and may strain system resources.
- Permissions: Ensure you have the necessary permissions to uninstall applications and delete files.
- Security Warning: Be cautious when deleting applications and files to avoid data loss.
- Shell Compatibility: The script is written for zsh. Ensure you have zsh installed.
This script relies on the following tools:
- jq: A lightweight and flexible command-line JSON processor.
- Homebrew: (macOS only) or Linuxbrew (optional on Linux).
- whiptail: A package for creating GUI dialogs in the terminal.
- newt: For terminal-based GUI dialogs.
Make sure these dependencies are installed before running the script.
When you confirm the deletion of an application, the script attempts to thoroughly remove it by deleting:
-
Main Application Files:
- On macOS: The application bundle from
/Applicationsand~/Applications. - On Linux: The corresponding .desktop files from
/usr/share/applicationsor~/.local/share/applications.
- On macOS: The application bundle from
-
Homebrew Files (macOS only):
- Uninstalls associated Homebrew formulas and casks installed via Homebrew.
Associated Files and Directories:
-
macOS:
- Application Support (optional):
~/Library/Application Support/<Application Name>/Library/Application Support/<Application Name>
- Preferences (optional):
~/Library/Preferences/com.<Application Name>.*/Library/Preferences/com.<Application Name>.*
- Caches (optional):
~/Library/Caches/<Application Name>~/Library/Caches/com.<Application Name>.*/Library/Caches/<Application Name>/Library/Caches/com.<Application Name>.*
- Logs (optional):
~/Library/Logs/<Application Name>/Library/Logs/<Application Name>
- Saved Application State (optional):
~/Library/Saved Application State/com.<Application Name>.*/Library/Saved Application State/com.<Application Name>.*
- Application Support (optional):
-
Linux:
- Application Data (optional):
$XDG_DATA_HOME/<AppName>~/.local/share/<AppName>
- Configuration Files (optional):
$XDG_CONFIG_HOME/<AppName>~/.config/<AppName>
- Cache Files (optional):
$XDG_CACHE_HOME/<AppName>~/.cache/<AppName>
- Log Files (optional):
- Common log directories (if any) related to the application
- Application Data (optional):
-
Additional Files Found via
sudo find(optional): Any files matching the application name found during thesudo findoperation (if you chose to include this step). The script will display these files and ask for your confirmation before deletion.
Please read the following carefully before using the script:
- Data Loss Risk: The script performs a thorough deletion of applications and their associated files. Be cautious when selecting applications to delete. Ensure that you do not remove essential system applications or files.
- Review Before Deleting: Before any files are deleted, the script will display a list of files and directories that will be removed. Please review this list carefully to avoid unintended deletions.
- No Undo: Deleting applications and files is permanent and cannot be undone. Consider backing up important data before proceeding.
- Use at Your Own Risk: The script is provided "as is," without warranty of any kind. The author is not responsible for any damage or data loss that may occur as a result of using this script.
If you have any questions or want to discuss the project further, feel free to connect with me on LinkedIn.
This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).
This license ensures that anyone who modifies, uses, or redistributes this software—especially in a networked environment—must share the source code and any modifications under the same license.
For detailed information, see the LICENSE file.