{"id":22692886,"url":"https://github.com/narekmosisian/mac-storage-manager","last_synced_at":"2025-04-12T07:18:12.797Z","repository":{"id":267166960,"uuid":"863495722","full_name":"NarekMosisian/mac-storage-manager","owner":"NarekMosisian","description":"A lightweight macOS \u0026 Linux tool for managing disk space by identifying and deleting large files, including Homebrew packages. Interactive and user-friendly CLI.","archived":false,"fork":false,"pushed_at":"2025-04-02T08:39:09.000Z","size":1971,"stargazers_count":50,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-12T07:18:02.636Z","etag":null,"topics":["application-management","automation","bash","cli","cli-tool","disk-cleaner","disk-cleanup","disk-usage","homebrew","linux","linux-shell","macos","open-source","performance","shell-script","utility","zsh","zshscript"],"latest_commit_sha":null,"homepage":"https://linktr.ee/narekmosisian","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NarekMosisian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-26T11:53:23.000Z","updated_at":"2025-04-06T06:44:17.000Z","dependencies_parsed_at":"2025-02-28T01:58:59.709Z","dependency_job_id":"e771410b-e7c4-48e6-975c-464c59cb2102","html_url":"https://github.com/NarekMosisian/mac-storage-manager","commit_stats":null,"previous_names":["narekmosisian/mac-storage-manager"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NarekMosisian%2Fmac-storage-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NarekMosisian%2Fmac-storage-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NarekMosisian%2Fmac-storage-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NarekMosisian%2Fmac-storage-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NarekMosisian","download_url":"https://codeload.github.com/NarekMosisian/mac-storage-manager/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248530604,"owners_count":21119601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["application-management","automation","bash","cli","cli-tool","disk-cleaner","disk-cleanup","disk-usage","homebrew","linux","linux-shell","macos","open-source","performance","shell-script","utility","zsh","zshscript"],"created_at":"2024-12-10T02:08:16.339Z","updated_at":"2025-04-12T07:18:12.790Z","avatar_url":"https://github.com/NarekMosisian.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mac Storage Manager – Cross-Platform Version (macOS \u0026 Linux)\n\n![CI](https://github.com/NarekMosisian/mac-storage-manager/actions/workflows/ci.yml/badge.svg)\n\nMac 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.\n\n\u003cimg src=\"./images/msm.png\" alt=\"Mac Storage Manager\" width=\"640\"/\u003e\n\n---\n\n## Table of Contents\n- [Features](#features)\n- [Log File](#log-file)\n- [Homebrew](#homebrew)\n- [Watch the Demo](#watch-the-demo)\n- [Continuous Integration](#continuous-integration)\n- [How to Use](#how-to-use)\n  - [Step 1: Clone the Repository](#step-1-clone-the-repository)\n  - [Step 2: Make the Script Executable](#step-2-make-the-script-executable)\n  - [Step 3: Install Dependencies](#step-3-install-dependencies)\n  - [Step 4: Run the Script](#step-4-run-the-script)\n  - [Step 5: Follow the Interactive Prompt](#step-5-follow-the-interactive-prompt)\n- [Known Limitations and Common Issues](#known-limitations-and-common-issues)\n- [Dependencies](#dependencies)\n- [What Exactly is Deleted](#what-exactly-is-deleted)\n- [Warning](#warning)\n- [Connect with me](#connect-with-me)\n- [License](#license)\n\n---\n\n## Features\n\n- **Cross-Platform Support**:  \n  - **macOS**: Scans `/Applications` and `~/Applications` for `.app` bundles.\n  - **Linux**: Scans `/usr/share/applications` and `~/.local/share/applications` for `.desktop` files.\n  \n- **Size Calculation**:  \n  - Calculates sizes for Homebrew formulas and casks (macOS only).\n  - Scans standard application directories.\n  - Optionally performs a comprehensive search using `sudo find`.\n\n- **Interactive Deletion**:  \n  - Graphical dialogs using whiptail for selecting applications to delete.\n  - Prompts for confirmation before deleting main files and associated files.\n\n- **Selective Associated File Deletion**:  \n  - **macOS**: Offers to remove Application Support, Preferences, Caches, Logs, and Saved Application State.\n  - **Linux**: Offers to remove Application Data, Configuration, Cache, and Log files based on XDG directories.\n\n- **Progress and Audio Feedback**:  \n  - Displays progress bars during long-running tasks.\n  - Plays sound effects for key actions (using `afplay` on macOS and `paplay` on Linux).\n\n- **Logging**:  \n  - Records errors and detailed process logs in `application_size_checker.log`.\n\n---\n\n## Log File\n\nThe 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:\n\n- **Timestamps**:  \n  - **Script Start and End**: Timestamps are explicitly logged at the beginning and the end of the script using the `date` command.\n\n- **Debug Information**:  \n  - The sound path used by the script is logged at the start (e.g., `DEBUG: SOUND_PATH=...`).  \n  - Outputs of commands like `ls -l` (for instance, the contents of the sound directory) are recorded.\n\n- **Error Messages and Warnings**:  \n  - Detailed logs are kept for errors when accessing files or deleting applications (both in the main script and when removing associated files).  \n  - Notifications for failed or canceled sudo password prompts, as well as any unsuccessful Homebrew operations (e.g., during uninstallation), are logged.\n\n- **Progress Updates**:  \n  - 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.\n\nThis 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.\n\n---\n\n## Homebrew\n\nFor 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:\n\n[**NarekMosisian/homebrew-mac-storage-manager**](https://github.com/NarekMosisian/homebrew-mac-storage-manager)\n\nThe tap also includes its own CI configuration to ensure continuous updates and error-free operation of the formula.\n\n---\n\n## Watch the Demo\n\n\u003ca href=\"https://www.youtube.com/watch?v=eO7GkXesK0Q\u0026ab_channel=NarekMosisian\"\u003e\n    \u003cimg src=\"./images/video.png\" alt=\"Watch the Demo on YouTube\" width=\"300\"/\u003e\n\u003c/a\u003e\n\n\u003e **Tip:** Hold down Ctrl (Windows/Linux) or Cmd (Mac) and click the image to open the video in a new tab.\n\nClick the image to watch the demo video on YouTube.\n\n---\n\n## Continuous Integration\n\nThis project uses GitHub Actions for continuous integration. Every push and pull request to the `main` branch triggers a workflow that:\n- Updates Homebrew (ignoring non-critical warnings)\n- Installs dependencies (jq, newt)\n- **Taps the external Homebrew repository** ([NarekMosisian/mac-storage-manager](https://github.com/NarekMosisian/homebrew-mac-storage-manager))\n- Installs the `mac-storage-manager` formula\n- Runs tests (using `brew test mac-storage-manager`)\n- Performs a strict audit of the formula\n\nYou can view the current CI status using the badge at the top.\n\n---\n\n## How to Use\n\n### Step 1: Clone the Repository\n\nClone the repository to your local machine:\n\n```bash\ngit clone https://github.com/NarekMosisian/mac-storage-manager.git\n```\n\n### Step 2: Make the Script Executable\n\nNavigate to the cloned directory and make the script executable by running:\n\n```bash\nchmod +x ./application_size_checker.sh\n```\n\n### Step 3: Install Dependencies\n\nThe script relies on several tools. Install them as follows:\n\n- **macOS** (using Homebrew):\n\n```bash\nbrew install jq newt\n```\n\n- **Linux** (using your package manager or Linuxbrew):\n\n```bash\n# On Debian/Ubuntu-based systems:\nsudo apt-get update\nsudo apt-get install jq newt paplay\n\n# Alternatively, if using Linuxbrew:\nbrew install jq newt\n```\nNote: On macOS, afplay is used for audio, while on Linux paplay is used.\n\n    jq: Parses JSON output from system commands.\n    newt: Provides terminal-based GUI dialogs (for interactive selection and progress bars).\n\n### Step 4: Run the Script\n\nLaunch the script by executing:\n\n```bash\n./application_size_checker.sh\n```\n\nOr, explicitly with zsh:\n\n```bash\nzsh ./application_size_checker.sh\n```\n\nNote: The script uses zsh. Ensure that zsh is installed and set as your default shell, or run the script explicitly with zsh:\n\n```bash\nzsh ./application_size_checker.sh\n```\n\n### Step 5: Follow the Interactive Prompt\n\nDuring the script's execution, you will be prompted with the following option:\n\n    Include sudo find: This step searches for all applications across the system but may take a long time to complete.\n\nOnce 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:\n\n    Prompt for confirmation before deleting each application and its associated files.\n    Display the list of files and directories that will be removed for each application.\n    Prompt you for each category of associated files (Application Support, Preferences, Caches, Logs, Saved Application State) whether you want to delete them.\n    Optionally delete any additional files found via sudo find that are associated with the application.\n\n---\n\n## Known Limitations and Common Issues\n\n- **Performance**: Searching the entire system with sudo find can be time-consuming and may strain system resources.\n- **Permissions**: Ensure you have the necessary permissions to uninstall applications and delete files.\n- **Security Warning**: Be cautious when deleting applications and files to avoid data loss.\n- **Shell Compatibility**: The script is written for zsh. Ensure you have zsh installed.\n\n---\n\n## Dependencies\n\nThis script relies on the following tools:\n\n- **jq**: A lightweight and flexible command-line JSON processor.\n- **Homebrew**: (macOS only) or **Linuxbrew** (optional on Linux).\n- **whiptail**: A package for creating GUI dialogs in the terminal.\n- **newt**: For terminal-based GUI dialogs.\n\nMake sure these dependencies are installed before running the script.\n\n---\n\n## What Exactly is Deleted\n\nWhen you confirm the deletion of an application, the script attempts to thoroughly remove it by deleting:\n\n- **Main Application Files**: \n    - **On macOS**: The application bundle from `/Applications` and `~/Applications`.\n    - **On Linux**: The corresponding .desktop files from `/usr/share/applications` or `~/.local/share/` applications.\n\n- **Homebrew Files** (macOS only):\n    - Uninstalls associated Homebrew formulas and casks installed via Homebrew.\n\n**Associated Files and Directories**:\n- **macOS**:\n    - **Application Support** (optional):\n        - `~/Library/Application Support/\u003cApplication Name\u003e`\n        - `/Library/Application Support/\u003cApplication Name\u003e`\n    - **Preferences** (optional):\n        - `~/Library/Preferences/com.\u003cApplication Name\u003e.*`\n        - `/Library/Preferences/com.\u003cApplication Name\u003e.*`\n    - **Caches** (optional):\n        - `~/Library/Caches/\u003cApplication Name\u003e`\n        - `~/Library/Caches/com.\u003cApplication Name\u003e.*`\n        - `/Library/Caches/\u003cApplication Name\u003e`\n        - `/Library/Caches/com.\u003cApplication Name\u003e.*`\n    - **Logs** (optional):\n        - `~/Library/Logs/\u003cApplication Name\u003e`\n        - `/Library/Logs/\u003cApplication Name\u003e`\n    - **Saved Application State** (optional):\n        - `~/Library/Saved Application State/com.\u003cApplication Name\u003e.*`\n        - `/Library/Saved Application State/com.\u003cApplication Name\u003e.*`\n\n- **Linux**:\n    - **Application Data** (optional):\n        - `$XDG_DATA_HOME/\u003cAppName\u003e`\n        - `~/.local/share/\u003cAppName\u003e`\n    - **Configuration Files** (optional):\n        - `$XDG_CONFIG_HOME/\u003cAppName\u003e`\n        - `~/.config/\u003cAppName\u003e`\n    - **Cache Files** (optional):\n        - `$XDG_CACHE_HOME/\u003cAppName\u003e`\n        - `~/.cache/\u003cAppName\u003e`\n    - **Log Files** (optional):\n        - Common log directories (if any) related to the application\n\n- **Additional Files Found via `sudo find` (optional)**: Any files matching the application name found during the `sudo find` operation (if you chose to include this step). The script will display these files and ask for your confirmation before deletion.\n\n---\n\n## Warning\n\nPlease read the following carefully before using the script:\n\n- **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.\n- **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.\n- **No Undo**: Deleting applications and files is permanent and cannot be undone. Consider backing up important data before proceeding.\n- **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.\n\n---\n\n## Connect with me\n\nIf you have any questions or want to discuss the project further, feel free to connect with me on [LinkedIn](https://www.linkedin.com/in/narek-mosisian-484789291/).\n\n---\n\n## License\n\nThis project is licensed under the **GNU Affero General Public License v3.0 (AGPLv3)**.  \nThis 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.  \n\nFor detailed information, see the [LICENSE](./LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnarekmosisian%2Fmac-storage-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnarekmosisian%2Fmac-storage-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnarekmosisian%2Fmac-storage-manager/lists"}