# Setup

## What you need

| Requirement | Why | Have it already? |
|---|---|---|
| macOS | `cleanup.sh` calls `memory_pressure`, `vm_stat`, and `sysctl vm.swapusage`, which only exist on macOS. This will not run on Linux or Windows. | Almost certainly, if you're trying to speed up a MacBook. |
| `bash` or `sh` (built in) | The script's shebang is `#!/bin/bash`; it also runs fine invoked with `sh`. Ships with every Mac. | Yes, always. |
| Terminal app | To run the commands below. Use the built-in Terminal or iTerm2. | Yes, built in. |
| Full Disk Access for Terminal (optional) | Only needed if you want accurate numbers from the `/private/var/vm` and `/private/var/folders` checks in README Step 2. Not required for `cleanup.sh` itself. | Check System Settings → Privacy & Security → Full Disk Access. |
| Xcode command-line tools (optional) | Only needed for the `xcrun simctl` commands in README Step 2/3 (finding/removing old iOS simulators). Not required for `cleanup.sh`. | Only relevant if you do iOS development. |
| Docker / colima CLI (optional) | Only needed for the `docker system df` / `colima list` commands in README Step 2 (checking Docker's disk usage). Not required for `cleanup.sh`. | Only relevant if you use Docker/colima. |

**NOT needed:** no Docker required to run `cleanup.sh` itself (Docker commands in the README are optional diagnostics, not a dependency). No account or login of any kind. No GPU. No paid API or API key. No pip/npm packages — there is no package manager involved at all. No internet connection required to run the script.

## Install, step by step

This repo is one Markdown guide and one shell script — there is nothing to compile or `pip install`. "Install" here just means getting the files onto your Mac.

1. **Confirm you're on a Mac with a Terminal.**
   ```bash
   sw_vers
   ```
   What it does: prints your macOS version.
   Check it worked: you see output like `ProductName: macOS` and a version number. If this command is not found, you are not on macOS and this repo will not work for you.

2. **Clone the repo.** If you don't already have `git`, macOS will prompt you to install the Xcode Command Line Tools the first time you run a `git` command — accept that prompt, wait for it to finish, then re-run the clone command.
   ```bash
   git clone <this-repo-url>
   cd deep-clean-macbook
   ```
   What it does: downloads the guide and script to your machine and moves into that folder.
   Check it worked:
   ```bash
   ls
   ```
   Expected output includes `cleanup.sh`, `README.md`, and `SETUP.md`.

3. **Make the script executable (optional but convenient).**
   ```bash
   chmod +x cleanup.sh
   ```
   What it does: lets you run `./cleanup.sh` directly instead of `sh cleanup.sh`.
   Check it worked:
   ```bash
   ls -l cleanup.sh
   ```
   Expected output: the permissions column starts with `-rwx` (the `x` means executable).

That's it — there is no dependency manager, no build step, and no service to start.

## Configure

Nothing to configure. There are no environment variables, no config files, and no API keys anywhere in this repo — `cleanup.sh` only reads `$HOME` from your existing shell environment.

## Run it

Always run the diagnostic and dry-run steps before anything that deletes files.

```bash
sh cleanup.sh --diagnose
```

Success looks like: a printout with four sections — `Disk space (/ volume)`, `Memory pressure`, `Swap usage`, and `Pageouts / Swapins / Swapouts` — ending with a one-line rule of thumb about whether a cleanup will help. Nothing is deleted by this command.

Next, see what the cleanup would remove without removing it:

```bash
sh cleanup.sh
```

Success looks like: a list of `WOULD DELETE contents of (<size>): <path>` lines for `~/Library/Caches`, `~/Library/Developer/Xcode/DerivedData`, and `~/.Trash`, followed by `Dry run only — nothing was deleted.`

Only after reviewing that list, actually delete:

```bash
sh cleanup.sh --execute
sudo reboot
```

`--execute` requires the flag explicitly — there is no way to trigger real deletion by accident. The reboot is required afterward because swap space only clears on reboot, not by freeing disk space.

## Troubleshooting

1. **`zsh: permission denied: ./cleanup.sh`** — you tried to run it directly without executable permissions. Fix: either run `sh cleanup.sh` (works regardless of permissions) or `chmod +x cleanup.sh` first, then `./cleanup.sh`.

2. **`memory_pressure not available` in the `--diagnose` output** — this is handled gracefully by the script (it prints that message and continues), but it means that specific check didn't run. Fix: this can happen in restricted/managed environments; the disk-space (`df -h /`) and swap (`sysctl vm.swapusage`) sections still work and are usually enough on their own.

3. **`Unknown option: <flag>`** — you passed something other than `--dry-run`, `--diagnose`, `--execute`, or `--help`. Fix: check spelling — the script only accepts those four exact flags (case-sensitive, with the leading `--`).