Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
38 commits
Select commit Hold shift + click to select a range
32101c5
refactor(tui): run the interactive screen on Bubble Tea
devloop01 Nov 3, 2026
f8db5e5
feat(tui): style the screen with a highlighted row, spinner and key bar
devloop01 Nov 3, 2026
59bab14
feat(tui): ask before deleting, in a dialog over the list
devloop01 Nov 3, 2026
eed680c
docs: tighten wording in help, messages, screen and docs
devloop01 Nov 3, 2026
5dd549b
fix(tui): fit the confirm dialog to small terminals; ignore its keys …
devloop01 Nov 4, 2026
123e3a8
fix(tui): wait for the terminal's color reply before quitting
devloop01 Nov 4, 2026
e13fdc5
fix(tui): quit at end of input; finish deletions however the screen ends
devloop01 Nov 4, 2026
8a316db
ci: let Dependabot update Go modules
devloop01 Nov 4, 2026
2b26205
feat(tui): add margins, column names and [✓] checkboxes
devloop01 Nov 4, 2026
46a9998
feat(tui): group the list by project, with monorepos as one
devloop01 Nov 4, 2026
faec316
feat(tui): toggle the project view (t), add a key list (?) and Finder…
devloop01 Nov 4, 2026
5f7f869
fix(tui): quit with the key list open; fix project-view cursor and di…
devloop01 Nov 4, 2026
c6b1bc5
fix(projects): ignore empty workspaces; find projects with fewer file…
devloop01 Nov 4, 2026
495b1dc
feat(tui): collapse projects (←/→, c) and jump between them (tab)
devloop01 Nov 4, 2026
83657e2
feat(tui): indent a project's folders under its name
devloop01 Nov 4, 2026
f429afe
feat(tui): sort by size, last change or name (s)
devloop01 Nov 4, 2026
8104701
fix(tui): cycle sort columns left to right
devloop01 Nov 4, 2026
3449f95
feat(tui): add mouse support for scrolling, rows, checkboxes, columns…
devloop01 Nov 4, 2026
f03473d
feat(tui): show c fold all in the key bar; keep it within 80 columns
devloop01 Nov 4, 2026
33e0f8c
feat: clean Rust target and Python caches; group Cargo and Python pro…
devloop01 Nov 4, 2026
7fbfc86
feat(tui): show free disk space in the header
devloop01 Nov 4, 2026
35962e8
fix(tui): read free space off the UI thread, show a full disk, fit th…
devloop01 Nov 4, 2026
ac974dc
feat(tui): double-click a row to select it
devloop01 Nov 4, 2026
3dfccbd
feat(tui): remember the project view and sort order between runs
devloop01 Nov 4, 2026
3a1e6c2
docs: add a demo recording to the README (make demo)
devloop01 Nov 4, 2026
a15aa75
test: random-use and trap-folder tests for what gets deleted
devloop01 Nov 4, 2026
91ecbe2
fix: keep build folders git doesn't ignore; they may hold uncommitted…
devloop01 Nov 4, 2026
fdf46ca
feat(tui)!: enter selects or folds; d or ⌫ deletes
devloop01 Nov 4, 2026
668f0c9
docs: rewrite the README to start with install and use
devloop01 Nov 4, 2026
3d7c524
refactor(tui): share select and fold logic; fix comments left from en…
devloop01 Nov 4, 2026
deb1947
fix: delete only the exact folder the scan saw, so a swap can't redir…
devloop01 Nov 4, 2026
09236eb
feat(projects): list a Tauri app's web and Rust folders as one project
devloop01 Nov 4, 2026
ea0660c
feat: show sizes in decimal units, like Finder
devloop01 Nov 4, 2026
331dc0f
fix(tui): wait longer for a slow terminal's color reply, and drop lat…
devloop01 Nov 4, 2026
8e3c14b
feat: show when each folder changed, and free space, in the printed list
devloop01 Nov 4, 2026
579014e
fix(tui): find dialog buttons in the box, align the Size click area, …
devloop01 Nov 4, 2026
eaf26a4
fix(projects): never open a pipe or symlinked project file; read each…
devloop01 Nov 4, 2026
5de8d5b
test: aim trap candidates at Remove with real identities, so Vet is w…
devloop01 Nov 4, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# Opens a pull request when a pinned GitHub Action has a new version,
# updating the commit SHA and its version comment together.
# Opens a pull request when a pinned GitHub Action or a Go module has a new
# version. For actions it updates the commit SHA and its version comment
# together.
version: 2
updates:
- package-ecosystem: github-actions
Expand All @@ -9,3 +10,10 @@ updates:
groups:
actions:
patterns: ["*"]
- package-ecosystem: gomod
directory: /
schedule:
interval: monthly
groups:
go:
patterns: ["*"]
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,4 @@
bin/
dist/
demo/bin/
demo/projects/
52 changes: 33 additions & 19 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

[![test](https://github.com/devloop01/sweep/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/devloop01/sweep/actions/workflows/test.yml)

sweep is a small Go program with no dependencies outside the standard library.
sweep is a small Go program. Its dependencies are [Charm](https://github.com/charmbracelet)'s
Bubble Tea, Bubbles and Lip Gloss, which run and style the interactive screen (`tui.go`).
It builds for Apple Silicon Macs only (`//go:build darwin && arm64`).

## Build and test
Expand All @@ -13,6 +14,7 @@ Needs Go 1.27 or later.
make test # go vet + go test -race
make build # ./bin/sweep
make release # dist/sweep-darwin-arm64
make demo # re-record demo/sweep.gif for the README (needs vhs)
```

Tests only touch folders under `t.TempDir()`. The mount test attaches small
Expand All @@ -29,7 +31,7 @@ somewhere in your home:
```sh
mkdir -p ~/sweep-playground/app/node_modules/pkg ~/sweep-playground/app/.next ~/sweep-playground/site/dist
echo keep > ~/sweep-playground/app/package.json
cd ~/sweep-playground && ~/path/to/sweep/bin/sweep -n -b
cd ~/sweep-playground && ~/path/to/sweep/bin/sweep -n
```

## Layout
Expand All @@ -38,12 +40,14 @@ cd ~/sweep-playground && ~/path/to/sweep/bin/sweep -n -b
|---|---|
| `main.go` | Flags, prompt, output and exit codes |
| `term.go` | Scan status line, colors, terminal checks |
| `tui.go` | The interactive screen: keys, drawing, raw terminal mode |
| `tui.go` | The interactive screen: list (by project with t), keys, key list, drawing, confirm dialog |
| `upgrade.go` | `sweep upgrade` and the new-version check |
| `internal/sweep/targets.conf` | Built-in target lists, embedded in the binary |
| `internal/sweep/targets.go` | Parsing and validating `targets.conf` and the user's config |
| `internal/sweep/guard.go` | Which folders sweep refuses to run in |
| `internal/sweep/scan.go` | Walking, matching, sizes, and the re-check before delete (`Vet`) |
| `internal/sweep/git.go` | Whether a target may hold git-tracked files |
| `internal/sweep/git.go` | Whether a target may hold real files: tracked, or build output git doesn't ignore |
| `internal/sweep/project.go` | Which project a folder belongs to, for grouping on the screen |
| `internal/sweep/remove.go` | Deleting the vetted folders through an `os.Root` |
| `install.sh` | The `curl … \| sh` installer |

Expand All @@ -65,8 +69,11 @@ Every rule has tests. When in doubt, sweep skips a folder rather than deleting i
- **Folders that may hold real files are kept** (`keep` in `git.go`). Inside
a git repo, a target is kept if `git ls-files` lists anything in it (a
committed `dist`, scripts in `build`) or if git can't answer: it isn't
installed, times out, or the repo is broken. Outside a repo, git isn't run
and only `dist`, `build` and `out` are kept, since without git there's no
installed, times out, or the repo is broken. `dist`, `build`, `out` and
`target` are also kept unless `git check-ignore -v` shows a rule that names
the folder: untracked but not ignored may be new work, and a catch-all `*`
(a repo around the whole home folder) says nothing about it. Outside a
repo, git isn't run and those four are kept, since without git there's no
way to tell they're only build output. Kept folders aren't listed; sweep
prints how many it skipped. Checked during the scan and again before
deleting.
Expand All @@ -81,20 +88,27 @@ Every rule has tests. When in doubt, sweep skips a folder rather than deleting i
- **Re-check before delete.** Each folder must still be strictly inside DIR,
reached without going through a symlink, a real directory on the same
volume, and still a target. Deletion then goes through an `os.Root` opened
before the scan, so a folder swapped for a symlink at the last moment can't
lead outside DIR. Known limit: inside DIR, that race could still redirect a
delete to another target-named folder in DIR (see `remove.go`).
before the scan, so nothing can lead outside DIR, and it deletes a folder
only if it's the very one the scan saw (same device and inode), so a
symlink or rename swapped in at the last moment can't redirect it to
another folder inside DIR either. Known limit: a different folder swapped
into the target's exact place between that check and the delete (see
`remove.go`).
- **Interactive screen** (`tui.go`, when stdin and stdout are terminals and
neither `-n` nor `-y` is given). It opens at once and the scan fills it in
(`Progress.OnFound`). Space selects, enter deletes the selection (or the
highlighted folder), each through the same `Remove` re-check. As the list
re-sorts, the cursor and selections stay on their folders, never on a row,
so enter can't hit a folder that just slid under it; finished deletions
are matched by path. The cursor never moves on its own, so a held-down
enter deletes one folder. Anything typed before the screen opens is
discarded. Deletions run in the background, at most one per CPU; quitting
waits for them. The terminal is restored on every exit (q, Esc, Ctrl-C,
the window closing).
(`Progress.OnFound`). Space or enter selects (enter on a project's row
collapses or opens it, and never deletes). `d` or ⌫ opens a confirm dialog
for the selection (or the highlighted folder), and each confirmed folder
goes through the same `Remove` re-check. The dialog keeps the folders'
paths, so a re-sort while it's open can't change what gets deleted, and
Cancel has focus first and other keys are ignored, so a held-down `d`
never deletes. As the list
re-sorts, the cursor and selections stay on their folders, not rows;
until the first key the cursor stays on the top row. Finished deletions
are matched by path. Anything typed before the screen opens is discarded.
Deletions run in the background, at most one per CPU; quitting waits for
them, also on SIGTERM and SIGHUP. Bubble Tea restores the terminal on
every exit.
- **Prompt** (stdin a terminal but stdout not). Only `y`/`yes` proceeds.
Piped input cancels unless `--yes` is given.
- **Output.** Control, format and line-separator characters in names print as
Expand Down Expand Up @@ -140,7 +154,7 @@ downloads, and installs to `~/.local/bin` by default. Files downloaded with
`curl` aren't quarantined by macOS, which is why the binary runs even though
it isn't signed. Signing and notarising would need an Apple Developer account.

CI runs the installer on every push to make sure it still works.
CI runs the installer on every push.

The workflows pin each action to a commit SHA. Dependabot opens a pull request
each month when one of them has a new version.
Expand Down
9 changes: 8 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
VERSION := $(shell git describe --tags --always 2>/dev/null || echo dev)
LDFLAGS := -s -w -X main.version=$(VERSION)

.PHONY: test build release
.PHONY: test build release demo

test:
go vet ./... && go test -race ./...
Expand All @@ -11,3 +11,10 @@ build:

release:
CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -ldflags "$(LDFLAGS)" -o dist/sweep-darwin-arm64 .

# The README recording (demo/sweep.gif). Needs vhs: brew install vhs
demo:
go build -o demo/bin/sweep .
demo/setup.sh
vhs demo/sweep.tape
rm -rf demo/bin demo/projects
158 changes: 83 additions & 75 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,49 +1,38 @@
# sweep

Free up disk space by deleting `node_modules` and build caches (`.next`,
`.svelte-kit`, `.turbo`, …) from all your projects at once.
Clean up `node_modules` and build caches across all your projects, and get
your disk space back.

```
$ cd ~/Documents/Code
$ sweep
sweep 3 folders, 1.5 GB
↑↓ move space select a all enter delete q quit

[x] agency/web/node_modules 1.2 GB
> agency/web/.svelte-kit deleted
[ ] site/.vercel/output 12.0 KB

Selected 1 folder, 1.2 GB · enter deletes them
```

Everything it deletes comes back with `npm install` / `pnpm install` or your
next dev or build run.
![sweep listing build folders, grouping them by project, sorting by last change, and deleting two after confirming](demo/sweep.gif)

## Install

For Apple Silicon Macs.
On an Apple Silicon Mac:

```sh
curl -fsSL https://raw.githubusercontent.com/devloop01/sweep/main/install.sh | sh
```

Or, if you have Go: `go install github.com/devloop01/sweep@latest`
<details>
<summary>"command not found", Go, and checking the download</summary>

If your terminal then says `sweep: command not found`, add the install folder
to your PATH and open a new terminal:
If your terminal says `sweep: command not found`, add the install folder to
your PATH and open a new terminal:

```sh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile # use ~/go/bin if you installed with Go
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile
```

Please don't download the binary with your browser: macOS will block it,
because it isn't signed by Apple.
With Go installed, you can also run
`go install github.com/devloop01/sweep@latest` (it installs to `~/go/bin`).

The installer checks the download for you and prints its checksum. To check
a copy it installed later on, run `shasum -a 256 "$(which sweep)"` and compare it
with the `sha256` shown next to `sweep-darwin-arm64` on the
Don't download the binary with your browser: macOS blocks it because it isn't
signed by Apple. The installer checks the download and prints its checksum;
it should match the one on the
[release page](https://github.com/devloop01/sweep/releases/latest).

</details>

## Use

Go to the folder that holds your projects and run `sweep`:
Expand All @@ -53,88 +42,107 @@ cd ~/Documents/Code
sweep
```

The list opens right away and fills in while sweep scans, biggest first.
Move with ↑/↓ (or j/k), select folders with **space** (`a` selects all),
and press **enter** to delete them. With nothing selected, enter deletes the
highlighted folder. `q` quits.
Pick folders with space, press `d`, and confirm.

To just look, or to clean everything at once:
| Key | Does |
|---|---|
| `space` or `enter` | select a folder |
| `d` | delete the selected folders (sweep asks first) |
| `t` | group folders by project |
| `s` | sort by size, name, or last change |
| `?` | show every key |
| `q` | quit |

The mouse works too. sweep remembers your view and sort order for next time.

To just see what's there, or clean everything without asking:

```sh
sweep -n # only print the list, delete nothing
sweep -y # delete everything in the list, no questions
sweep -n # list only, delete nothing
sweep -y # delete everything in the list
```

In a long printed list, the many tiny folders (under 1 MB each) are shown as
one line, so the ones that matter stand out. You can also pass a folder
instead of using `cd`: `sweep -n ~/Documents/Code`.
## What it deletes

Only folders your tools rebuild for free, with `npm install` or your next
dev, build, cargo or test run:

## What gets deleted
- `node_modules`
- framework caches like `.next`, `.svelte-kit`, `.turbo` and `.nuxt`
- Python caches like `.pytest_cache` and `.mypy_cache`
- build output (`dist`, `build`, `out`, Rust's `target`), but only when your
`.gitignore` lists it

Only folders that are safe to throw away, because your tools rebuild them
for free:
<details>
<summary>The full list, and why build folders need .gitignore</summary>

- **Dependencies:** `node_modules`
- **Framework caches:** `.next` `.svelte-kit` `.turbo` `.nuxt` `.output`
`.astro` `.vite` `.parcel-cache` `.angular` `.docusaurus` `.nx` `.vinxi`
`storybook-static` and `.vercel/output`
- **Build output:** `dist` `build` `out`, but only in a git repo where git
confirms nothing inside is tracked. Projects sometimes keep real files in
these (a committed `dist`, scripts in `build`), so outside git, or when git
tracks files in them, sweep skips them and says how many it skipped.
- **Python caches:** `.pytest_cache` `.mypy_cache` `.ruff_cache`
- **Build output:** `dist` `build` `out` `target`

Projects sometimes keep real files in build folders: a committed `dist`,
scripts in `build`, or new files you haven't committed yet. So sweep deletes
them only in a git repo whose ignore rules name them, with nothing inside
tracked. Anything else is skipped, and sweep tells you how many.

sweep never deletes things that would make you set up a project again, like
`.vercel`, `.netlify` or `.wrangler`.

sweep never deletes anything that would make you set up a project again, like
`.vercel` or `.netlify` (your project link) or `.wrangler` (local Cloudflare
data). You can add those yourself if you want.
</details>

## Safety

- sweep asks before deleting anything, unless you pass `-y`.
- It only deletes folders with the names above, never your code.
- It won't run in your home folder, `~/Library`, system folders, or with
`sudo`.
- It doesn't follow symlinks, never touches `.git` folders or apps, and
stays on your Mac's drive.

To keep sweep out of a folder, put an empty `.sweepignore` file in it.

## Customize

Create `~/.config/sweep/targets.conf`, one folder name per line, like a
`.gitignore`:
To delete more folder names, or stop deleting some, create
`~/.config/sweep/targets.conf`:

```
# also delete these
.cache
coverage

# never delete these
!.output
!out
```

Names you list are deleted too. Put `!` in front of a name to stop deleting
it. `parent/child` deletes only `child` inside `parent`, like `.vercel/output`.
If the file has a mistake, sweep tells you the line and doesn't run.
<details>
<summary>More on targets.conf</summary>

## Skip a folder
It works like a `.gitignore`: one folder name per line, `!` in front of a
name to stop deleting it, and `parent/child` to delete `child` only inside
`parent` (like `.vercel/output`). If the file has a mistake, sweep tells you
the line and doesn't run.

To keep sweep out of a folder, put an empty `.sweepignore` file in it:
</details>

## Upgrade or uninstall

```sh
touch ~/Documents/Code/my-project/.sweepignore
sweep upgrade # sweep also tells you when one is out
rm "$(which sweep)" && rm -rf ~/.local/state/sweep # uninstall
```

sweep won't look inside that folder at all, so nothing in it is ever deleted.
<details>
<summary>Why the freed space can look smaller than shown</summary>

## Is it safe?

sweep only deletes folders with the names above, and always shows you the
list first. It also:

- won't run in your home folder, `~/Library`, system folders, or with `sudo`
- never follows shortcuts (symlinks), and never touches `.git` folders or apps
- skips any folder that git tracks files in
- stays on your Mac's drive: it won't go into network shares or USB drives
mounted inside the folder

Sizes are real disk usage. With pnpm, the freed space can be smaller than
shown, because pnpm keeps a shared copy of every package.

## Upgrade or uninstall
Sizes are real disk usage. With pnpm, the space you get back can be smaller,
because pnpm keeps one shared copy of every package. On a Mac with Time
Machine snapshots, freed space can also show up a little later.

- **Upgrade:** `sweep upgrade`, or run the install command again. sweep checks for a new release while it runs and tells you when there is one.
- **Uninstall:** `rm "$(which sweep)"`. sweep is a single file and leaves
nothing else behind.
</details>

---

Expand Down
Loading
Loading