reclaimable 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/.claude/launch.json +11 -0
- data/.gitignore +11 -0
- data/.gitlab-ci.yml +16 -0
- data/AGENTS.md +88 -0
- data/CLAUDE.md +1 -0
- data/Gemfile +3 -0
- data/LICENSE +674 -0
- data/README.md +160 -0
- data/Rakefile +28 -0
- data/ai-skill/reclaimable/SKILL.md +94 -0
- data/benchmark/README.md +59 -0
- data/benchmark/experiments/lstat_scanner.rb +11 -0
- data/benchmark/experiments/ractor_scanner.rb +92 -0
- data/benchmark/experiments/verify_bulk_list.rb +34 -0
- data/benchmark/lib/fixture.rb +104 -0
- data/benchmark/lib/results.rb +62 -0
- data/benchmark/reports/00-baseline.md +75 -0
- data/benchmark/reports/01-jit.md +70 -0
- data/benchmark/reports/02-ractor.md +58 -0
- data/benchmark/reports/03-getattrlistbulk.md +84 -0
- data/benchmark/reports/04-others.md +52 -0
- data/benchmark/reports/05-outside-root.md +56 -0
- data/benchmark/reports/06-round2-discussion.md +374 -0
- data/benchmark/reports/06-round2.md +194 -0
- data/benchmark/reports/README.md +46 -0
- data/benchmark/results/baseline.yml +126 -0
- data/benchmark/results/bulk-list.yml +126 -0
- data/benchmark/results/final-yjit.yml +126 -0
- data/benchmark/results/final.yml +126 -0
- data/benchmark/results/ractor-exp.yml +38 -0
- data/benchmark/results/round2-after.yml +126 -0
- data/benchmark/results/round2-before.yml +126 -0
- data/benchmark/results/src-baseline.yml +32 -0
- data/benchmark/results/src-bulk-list.yml +32 -0
- data/benchmark/results/src-pair-none1.yml +38 -0
- data/benchmark/results/src-pair-none2.yml +38 -0
- data/benchmark/results/src-pair-yjit1.yml +38 -0
- data/benchmark/results/src-pair-yjit2.yml +38 -0
- data/benchmark/results/src-ractor-exp.yml +32 -0
- data/benchmark/results/src-round2-after1.yml +52 -0
- data/benchmark/results/src-round2-after2.yml +52 -0
- data/benchmark/results/src-round2-before1.yml +52 -0
- data/benchmark/results/src-round2-before2.yml +52 -0
- data/benchmark/results/yjit.yml +126 -0
- data/benchmark/results/zjit.yml +126 -0
- data/benchmark/run.rb +149 -0
- data/bin/reclaimable +10 -0
- data/doc/performance.md +179 -0
- data/lib/reclaimable/ai_skill.rb +138 -0
- data/lib/reclaimable/bulk_list.rb +91 -0
- data/lib/reclaimable/cache_dump.rb +125 -0
- data/lib/reclaimable/cli.rb +168 -0
- data/lib/reclaimable/cloud_files.rb +33 -0
- data/lib/reclaimable/config.rb +100 -0
- data/lib/reclaimable/i18n.rb +24 -0
- data/lib/reclaimable/locations.rb +89 -0
- data/lib/reclaimable/output.rb +154 -0
- data/lib/reclaimable/paths.rb +36 -0
- data/lib/reclaimable/report.rb +504 -0
- data/lib/reclaimable/ruby_abi.rb +69 -0
- data/lib/reclaimable/scan_cache.rb +97 -0
- data/lib/reclaimable/scanner.rb +440 -0
- data/lib/reclaimable/util.rb +34 -0
- data/lib/reclaimable.rb +42 -0
- data/locale/ja/LC_MESSAGES/reclaimable.mo +0 -0
- data/man/reclaimable.1.ronn +302 -0
- data/man/reclaimable.en.1 +234 -0
- data/man/reclaimable.ja.1 +452 -0
- data/po/ja/reclaimable-docs.po +668 -0
- data/po/ja/reclaimable.po +510 -0
- data/rakelib/benchmark.rake +22 -0
- data/rakelib/docs/japanese.rb +132 -0
- data/rakelib/docs/man_page.rb +73 -0
- data/rakelib/docs/site.rb +187 -0
- data/rakelib/docs/sources.rb +94 -0
- data/rakelib/docs/translation.rb +157 -0
- data/rakelib/docs.rake +62 -0
- data/rakelib/gettext.rake +30 -0
- data/rakelib/i18n.rake +199 -0
- data/reclaimable.gemspec +56 -0
- data/site/index.md +142 -0
- data/site/layout.html.erb +60 -0
- data/site/style.css +82 -0
- metadata +231 -0
|
@@ -0,0 +1,302 @@
|
|
|
1
|
+
reclaimable(1) -- find what is eating disk space on your Mac, without deleting anything
|
|
2
|
+
=======================================================================================
|
|
3
|
+
|
|
4
|
+
## SYNOPSIS
|
|
5
|
+
|
|
6
|
+
`reclaimable` [`-n` <count>] [`-s` <mb>] [`-d` <directory>] [`-o` <directory>] [`-j` <threads>] [`--no-save`] [`--fresh`]
|
|
7
|
+
|
|
8
|
+
## DESCRIPTION
|
|
9
|
+
|
|
10
|
+
**reclaimable** is a read-only command-line tool for macOS that lists what is
|
|
11
|
+
taking up storage and what you can probably reclaim: regenerable caches, build
|
|
12
|
+
artifacts, gems left behind by old Ruby versions, container disk images, large
|
|
13
|
+
files, and Time Machine local snapshots. It sorts the findings by size.
|
|
14
|
+
|
|
15
|
+
It never deletes anything and never needs `sudo`. It only reads what the
|
|
16
|
+
logged-in user can read, and leaves the decision of what to remove to you.
|
|
17
|
+
|
|
18
|
+
It walks the start directory (your home directory by default) once, in
|
|
19
|
+
parallel, and builds every section of the report from that single scan.
|
|
20
|
+
Scan results are cached, so a second run skips directories that have not
|
|
21
|
+
changed.
|
|
22
|
+
|
|
23
|
+
Messages and the report are in Japanese when your locale is Japanese, and in
|
|
24
|
+
English otherwise. See [ENVIRONMENT][].
|
|
25
|
+
|
|
26
|
+
## OPTIONS
|
|
27
|
+
|
|
28
|
+
* `-n` <count>:
|
|
29
|
+
Number of entries shown in each ranking. Default: 20.
|
|
30
|
+
|
|
31
|
+
* `-s` <mb>:
|
|
32
|
+
Smallest size, in megabytes, that counts as a "large file". Default: 1024.
|
|
33
|
+
|
|
34
|
+
* `-d` <directory>:
|
|
35
|
+
Directory to start scanning from. Default: your home directory.
|
|
36
|
+
|
|
37
|
+
* `-o` <directory>:
|
|
38
|
+
Directory to save the report and the log in.
|
|
39
|
+
Default: the log directory (see [FILES][]), which is
|
|
40
|
+
`~/Library/Logs/reclaimable` on macOS.
|
|
41
|
+
|
|
42
|
+
* `--save`, `--no-save`:
|
|
43
|
+
Also save the report and the log to files. Default: save.
|
|
44
|
+
|
|
45
|
+
* `-j` <threads>:
|
|
46
|
+
Number of threads that scan in parallel, from 1 to 64.
|
|
47
|
+
Default: the number of CPUs, up to 8.
|
|
48
|
+
|
|
49
|
+
* `--fresh`:
|
|
50
|
+
Ignore the cached scan results and scan everything again.
|
|
51
|
+
|
|
52
|
+
* `--freeze` <directory>:
|
|
53
|
+
Measure <directory> once, save its size to the config file, and skip it in
|
|
54
|
+
later scans. Use this for large folders that never change, such as an old
|
|
55
|
+
copy of a website with many small files. Later scans use the saved size
|
|
56
|
+
instead of reading the folder. Give it again to measure the folder again.
|
|
57
|
+
It can be given more than once. With this option, reclaimable only updates
|
|
58
|
+
the config file and does not make a report.
|
|
59
|
+
|
|
60
|
+
* `--unfreeze` <directory>:
|
|
61
|
+
Remove <directory> from the frozen folders, so it is scanned again.
|
|
62
|
+
It can be given more than once.
|
|
63
|
+
|
|
64
|
+
* `--dump-cache` [<format>]:
|
|
65
|
+
Print the cached scan results for the start directory (`-d`) and exit,
|
|
66
|
+
without scanning. <format> is `text` (a table for people, the default),
|
|
67
|
+
`json`, or `yaml`. Each folder has its modification time, the total size of
|
|
68
|
+
the small files directly in it, the names of its subfolders, and the names
|
|
69
|
+
of its large files. The cache itself is a binary file (Ruby's Marshal,
|
|
70
|
+
compressed with gzip), so use this option to see what it holds.
|
|
71
|
+
|
|
72
|
+
* `--config` <file>:
|
|
73
|
+
Config file to use. Default: see [FILES][].
|
|
74
|
+
|
|
75
|
+
* `--ai-skill`:
|
|
76
|
+
Show the skill for AI agents, where it is, and how to install it, and
|
|
77
|
+
exit. Nothing is written. See [AI AGENT SKILL][].
|
|
78
|
+
|
|
79
|
+
* `--install-ai-skill` [<directory>]:
|
|
80
|
+
Install the skill for AI agents in the skill directory <directory>, as
|
|
81
|
+
<directory>`/reclaimable`, and exit. Files that are already there are
|
|
82
|
+
overwritten. Without <directory>, reclaimable asks where to install it. It
|
|
83
|
+
can be given more than once. See [AI AGENT SKILL][].
|
|
84
|
+
|
|
85
|
+
* `--man`:
|
|
86
|
+
Show this manual, in Japanese when your locale is Japanese and in English
|
|
87
|
+
otherwise.
|
|
88
|
+
|
|
89
|
+
* `-h`, `--help`:
|
|
90
|
+
Show a short usage message.
|
|
91
|
+
|
|
92
|
+
## REPORT
|
|
93
|
+
|
|
94
|
+
The report has these sections, in this order:
|
|
95
|
+
|
|
96
|
+
* Whole disk:
|
|
97
|
+
`df -h` for the data volume.
|
|
98
|
+
|
|
99
|
+
* Largest folders:
|
|
100
|
+
The largest folders directly under the start directory, and what is inside them.
|
|
101
|
+
|
|
102
|
+
* Usually regenerable:
|
|
103
|
+
Known cache and download locations of 100 MB or more, such as `~/Library/Caches`,
|
|
104
|
+
the Homebrew cache, npm/pnpm/yarn/bun caches, Cargo registries, Xcode DerivedData,
|
|
105
|
+
iOS simulators, Ollama and Hugging Face models, gem documentation, and iPhone
|
|
106
|
+
backups, each with a note on what happens if you remove it.
|
|
107
|
+
|
|
108
|
+
* Build artifacts and dependencies:
|
|
109
|
+
`node_modules`, `.venv`, `venv`, `.build`, `.dart_tool`, and Cargo `target`
|
|
110
|
+
folders of 50 MB or more, with the date each was last modified, so you can
|
|
111
|
+
spot projects you no longer touch.
|
|
112
|
+
|
|
113
|
+
* Ruby gems:
|
|
114
|
+
`vendor/bundle` and user gem directories, split by Ruby version, marking
|
|
115
|
+
the ones left behind by Ruby versions that are no longer used or installed.
|
|
116
|
+
`vendor/bundle` is split by ABI version (such as 4.0.0). User gem directories
|
|
117
|
+
are named by ABI version, or by full version (such as 4.0.9) when chruby
|
|
118
|
+
manages them; both are matched against the installed Rubies. For user gem
|
|
119
|
+
directories, the size of their documentation is also shown.
|
|
120
|
+
|
|
121
|
+
* Containers:
|
|
122
|
+
Data folders and disk images of Docker Desktop, Colima, Lima, OrbStack,
|
|
123
|
+
Podman, and Rancher Desktop, both the real usage and the apparent size of the
|
|
124
|
+
sparse disk images, plus `docker system df` for each running Docker engine.
|
|
125
|
+
Contexts that point to the same engine are shown only once.
|
|
126
|
+
|
|
127
|
+
* Large files:
|
|
128
|
+
Files of at least the `-s` size, outside the Trash.
|
|
129
|
+
|
|
130
|
+
* Time Machine local snapshots:
|
|
131
|
+
`tmutil listlocalsnapshots /`.
|
|
132
|
+
|
|
133
|
+
* Estimates from other tools:
|
|
134
|
+
`brew cleanup -n`, `ollama list`, `rustup toolchain list`, and unavailable
|
|
135
|
+
iOS simulators.
|
|
136
|
+
|
|
137
|
+
* Frozen folders:
|
|
138
|
+
Folders frozen with `--freeze`, with the size and the date they were
|
|
139
|
+
measured. Large files and build artifacts inside them do not appear in the
|
|
140
|
+
sections above. A folder is marked when it has changed since it was
|
|
141
|
+
measured (files were added, removed, or renamed directly inside it).
|
|
142
|
+
This section appears only when there are such folders.
|
|
143
|
+
|
|
144
|
+
* Unreadable locations:
|
|
145
|
+
Folders that could not be read and are therefore missing from the totals.
|
|
146
|
+
|
|
147
|
+
* Cloud-only folders:
|
|
148
|
+
Folders whose contents live only in iCloud Drive, Google Drive, or other
|
|
149
|
+
cloud storage. They were not read and use almost no local space.
|
|
150
|
+
This section appears only when there are such folders.
|
|
151
|
+
|
|
152
|
+
## FILES
|
|
153
|
+
|
|
154
|
+
Where each kind of file goes is decided in this order. If the XDG environment
|
|
155
|
+
variable for that kind is set to an absolute path, the directory under it is
|
|
156
|
+
used on any system (see [ENVIRONMENT][]). Otherwise, macOS uses the places
|
|
157
|
+
under `~/Library` that Apple's conventions give, and other systems such as
|
|
158
|
+
Linux use the XDG defaults.
|
|
159
|
+
|
|
160
|
+
* Log directory:
|
|
161
|
+
`$XDG_STATE_HOME/reclaimable` if `XDG_STATE_HOME` is set. Otherwise
|
|
162
|
+
`~/Library/Logs/reclaimable` on macOS and `~/.local/state/reclaimable`
|
|
163
|
+
elsewhere. It holds the report, <YYYYmmdd-HHMMSS>`.report.txt`, and the
|
|
164
|
+
log, <YYYYmmdd-HHMMSS>`.log`, one of each per run. The log has failed
|
|
165
|
+
commands, every unreadable location, and timings.
|
|
166
|
+
|
|
167
|
+
* Cache directory:
|
|
168
|
+
`$XDG_CACHE_HOME/reclaimable` if `XDG_CACHE_HOME` is set. Otherwise
|
|
169
|
+
`~/Library/Caches/reclaimable` on macOS and `~/.cache/reclaimable`
|
|
170
|
+
elsewhere. It holds cached scan results, one file per start directory. A
|
|
171
|
+
cache older than 7 days is ignored. `--dump-cache` shows what a cache holds.
|
|
172
|
+
|
|
173
|
+
* Config file:
|
|
174
|
+
`$XDG_CONFIG_HOME/reclaimable/config.yml` if `XDG_CONFIG_HOME` is set.
|
|
175
|
+
Otherwise `~/Library/Application Support/reclaimable/config.yml` on macOS
|
|
176
|
+
and `~/.config/reclaimable/config.yml` elsewhere. It is in YAML and holds
|
|
177
|
+
the frozen folders: for each, the size, the modification time of the
|
|
178
|
+
folder, and when it was measured. Paths start with `~`. `--freeze` and
|
|
179
|
+
`--unfreeze` write it. You can also edit it by hand, but comments are lost
|
|
180
|
+
when they rewrite it.
|
|
181
|
+
|
|
182
|
+
A config file with one frozen folder looks like this:
|
|
183
|
+
|
|
184
|
+
frozen:
|
|
185
|
+
"~/archive/old-site":
|
|
186
|
+
bytes: 19579686912
|
|
187
|
+
mtime: 1683312343701143794
|
|
188
|
+
measured_at: '2026-11-15T23:15:44+09:00'
|
|
189
|
+
|
|
190
|
+
## ENVIRONMENT
|
|
191
|
+
|
|
192
|
+
* `XDG_CONFIG_HOME`:
|
|
193
|
+
Base directory for the config file. See [FILES][].
|
|
194
|
+
|
|
195
|
+
* `XDG_STATE_HOME`:
|
|
196
|
+
Base directory for the report and the log. See [FILES][].
|
|
197
|
+
|
|
198
|
+
* `XDG_CACHE_HOME`:
|
|
199
|
+
Base directory for the scan cache. See [FILES][].
|
|
200
|
+
|
|
201
|
+
* `LC_ALL`, `LC_MESSAGES`, `LANG`:
|
|
202
|
+
The language of messages and the report, checked in this order. If the first
|
|
203
|
+
one that is set starts with `ja` (for example `ja_JP.UTF-8`), they are in
|
|
204
|
+
Japanese. Otherwise they are in English. To get English once, run
|
|
205
|
+
`LC_ALL=C reclaimable`.
|
|
206
|
+
|
|
207
|
+
## NOTES
|
|
208
|
+
|
|
209
|
+
Folders such as Desktop, Documents, Downloads, and Mail are protected by macOS
|
|
210
|
+
privacy controls. Unless your terminal app has Full Disk Access, they cannot be
|
|
211
|
+
read, and they are listed at the end of the report. To include them, give the
|
|
212
|
+
terminal app Full Disk Access in System Settings and run again. `sudo` is not
|
|
213
|
+
needed.
|
|
214
|
+
|
|
215
|
+
reclaimable does not download files that live only in the cloud. Reading such
|
|
216
|
+
a folder would normally make macOS download it, so reclaimable turns that off
|
|
217
|
+
for its own process and lists those folders in the report instead. If it
|
|
218
|
+
cannot turn it off, it skips `~/Library/Mobile Documents` and
|
|
219
|
+
`~/Library/CloudStorage` and says so.
|
|
220
|
+
|
|
221
|
+
Sizes are the space actually used on disk (allocated blocks), not the apparent
|
|
222
|
+
file size. Files that live only in the cloud (Dropbox or iCloud "online only")
|
|
223
|
+
and sparse files are counted smaller than they look in Finder.
|
|
224
|
+
|
|
225
|
+
## EXAMPLES
|
|
226
|
+
|
|
227
|
+
Scan your home directory and save the report:
|
|
228
|
+
|
|
229
|
+
$ reclaimable
|
|
230
|
+
|
|
231
|
+
Show the top 50 entries and treat files of 500 MB or more as large:
|
|
232
|
+
|
|
233
|
+
$ reclaimable -n 50 -s 500
|
|
234
|
+
|
|
235
|
+
Scan only `~/src`, ignore the cache, and do not save files:
|
|
236
|
+
|
|
237
|
+
$ reclaimable -d ~/src --fresh --no-save
|
|
238
|
+
|
|
239
|
+
Freeze a large folder that never changes, so later scans skip it:
|
|
240
|
+
|
|
241
|
+
$ reclaimable --freeze ~/archive/old-site
|
|
242
|
+
|
|
243
|
+
## INSTALLATION
|
|
244
|
+
|
|
245
|
+
reclaimable needs Ruby 4.0 or later. Its only runtime gem dependency is
|
|
246
|
+
gettext, for translated messages.
|
|
247
|
+
|
|
248
|
+
$ gem install reclaimable
|
|
249
|
+
|
|
250
|
+
To read this manual from the installed gem, run `reclaimable --man`. It opens
|
|
251
|
+
the Japanese version when your locale is Japanese, and the English version
|
|
252
|
+
otherwise.
|
|
253
|
+
|
|
254
|
+
$ reclaimable --man
|
|
255
|
+
|
|
256
|
+
You can also read it with gem-man. When asked which manual to open, choose
|
|
257
|
+
`reclaimable.en.1` for English or `reclaimable.ja.1` for Japanese.
|
|
258
|
+
|
|
259
|
+
$ gem install gem-man
|
|
260
|
+
$ gem man reclaimable
|
|
261
|
+
|
|
262
|
+
## AI AGENT SKILL
|
|
263
|
+
|
|
264
|
+
The gem includes a skill for AI agents such as Claude Code and Codex, in the
|
|
265
|
+
Agent Skills format (<https://agentskills.io>). It tells the agent how to run
|
|
266
|
+
reclaimable, how to read the report, and never to delete anything without
|
|
267
|
+
asking you. The gem does not install it for you.
|
|
268
|
+
|
|
269
|
+
To see the skill and the commands that install it by hand:
|
|
270
|
+
|
|
271
|
+
$ reclaimable --ai-skill
|
|
272
|
+
|
|
273
|
+
To let reclaimable install it:
|
|
274
|
+
|
|
275
|
+
$ reclaimable --install-ai-skill
|
|
276
|
+
|
|
277
|
+
It lists the skill directories that exist, `~/.claude/skills` (Claude Code)
|
|
278
|
+
and `~/.agents/skills` (Codex and other agents), and asks which to use. You
|
|
279
|
+
can choose more than one, or enter another directory. It asks again before it
|
|
280
|
+
overwrites a skill that is already installed. When standard input is not a
|
|
281
|
+
terminal, it does not ask: it shows how to give the directory and exits with
|
|
282
|
+
an error.
|
|
283
|
+
|
|
284
|
+
To install it without being asked, give the skill directory. This is the form
|
|
285
|
+
for scripts and for agents:
|
|
286
|
+
|
|
287
|
+
$ reclaimable --install-ai-skill=~/.claude/skills
|
|
288
|
+
|
|
289
|
+
The skill is copied to `reclaimable` in that directory. If that is a symbolic
|
|
290
|
+
link, nothing is written. The copy is not updated with the gem, so install it
|
|
291
|
+
again after you update reclaimable.
|
|
292
|
+
|
|
293
|
+
## LICENSE
|
|
294
|
+
|
|
295
|
+
reclaimable is free software, released under the GNU General Public License,
|
|
296
|
+
version 3 or (at your option) any later version.
|
|
297
|
+
|
|
298
|
+
## SEE ALSO
|
|
299
|
+
|
|
300
|
+
df(1), du(1), tmutil(8), brew(1), docker(1)
|
|
301
|
+
|
|
302
|
+
<https://kitaitimakoto.gitlab.io/reclaimable/>
|
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
.\" generated with Ronn-NG/v0.10.1
|
|
2
|
+
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
|
|
3
|
+
.TH "RECLAIMABLE" "1" "November 2026" "reclaimable 0.1.0"
|
|
4
|
+
.SH "NAME"
|
|
5
|
+
\fBreclaimable\fR \- find what is eating disk space on your Mac, without deleting anything
|
|
6
|
+
.SH "SYNOPSIS"
|
|
7
|
+
\fBreclaimable\fR [\fB\-n\fR \fIcount\fR] [\fB\-s\fR \fImb\fR] [\fB\-d\fR \fIdirectory\fR] [\fB\-o\fR \fIdirectory\fR] [\fB\-j\fR \fIthreads\fR] [\fB\-\-no\-save\fR] [\fB\-\-fresh\fR]
|
|
8
|
+
.SH "DESCRIPTION"
|
|
9
|
+
\fBreclaimable\fR is a read\-only command\-line tool for macOS that lists what is taking up storage and what you can probably reclaim: regenerable caches, build artifacts, gems left behind by old Ruby versions, container disk images, large files, and Time Machine local snapshots\. It sorts the findings by size\.
|
|
10
|
+
.P
|
|
11
|
+
It never deletes anything and never needs \fBsudo\fR\. It only reads what the logged\-in user can read, and leaves the decision of what to remove to you\.
|
|
12
|
+
.P
|
|
13
|
+
It walks the start directory (your home directory by default) once, in parallel, and builds every section of the report from that single scan\. Scan results are cached, so a second run skips directories that have not changed\.
|
|
14
|
+
.P
|
|
15
|
+
Messages and the report are in Japanese when your locale is Japanese, and in English otherwise\. See \fIENVIRONMENT\fR\.
|
|
16
|
+
.SH "OPTIONS"
|
|
17
|
+
.TP
|
|
18
|
+
\fB\-n\fR \fIcount\fR
|
|
19
|
+
Number of entries shown in each ranking\. Default: 20\.
|
|
20
|
+
.TP
|
|
21
|
+
\fB\-s\fR \fImb\fR
|
|
22
|
+
Smallest size, in megabytes, that counts as a "large file"\. Default: 1024\.
|
|
23
|
+
.TP
|
|
24
|
+
\fB\-d\fR \fIdirectory\fR
|
|
25
|
+
Directory to start scanning from\. Default: your home directory\.
|
|
26
|
+
.TP
|
|
27
|
+
\fB\-o\fR \fIdirectory\fR
|
|
28
|
+
Directory to save the report and the log in\. Default: the log directory (see \fIFILES\fR), which is \fB~/Library/Logs/reclaimable\fR on macOS\.
|
|
29
|
+
.TP
|
|
30
|
+
\fB\-\-save\fR, \fB\-\-no\-save\fR
|
|
31
|
+
Also save the report and the log to files\. Default: save\.
|
|
32
|
+
.TP
|
|
33
|
+
\fB\-j\fR \fIthreads\fR
|
|
34
|
+
Number of threads that scan in parallel, from 1 to 64\. Default: the number of CPUs, up to 8\.
|
|
35
|
+
.TP
|
|
36
|
+
\fB\-\-fresh\fR
|
|
37
|
+
Ignore the cached scan results and scan everything again\.
|
|
38
|
+
.TP
|
|
39
|
+
\fB\-\-freeze\fR \fIdirectory\fR
|
|
40
|
+
Measure \fIdirectory\fR once, save its size to the config file, and skip it in later scans\. Use this for large folders that never change, such as an old copy of a website with many small files\. Later scans use the saved size instead of reading the folder\. Give it again to measure the folder again\. It can be given more than once\. With this option, reclaimable only updates the config file and does not make a report\.
|
|
41
|
+
.TP
|
|
42
|
+
\fB\-\-unfreeze\fR \fIdirectory\fR
|
|
43
|
+
Remove \fIdirectory\fR from the frozen folders, so it is scanned again\. It can be given more than once\.
|
|
44
|
+
.TP
|
|
45
|
+
\fB\-\-dump\-cache\fR [\fIformat\fR]
|
|
46
|
+
Print the cached scan results for the start directory (\fB\-d\fR) and exit, without scanning\. \fIformat\fR is \fBtext\fR (a table for people, the default), \fBjson\fR, or \fByaml\fR\. Each folder has its modification time, the total size of the small files directly in it, the names of its subfolders, and the names of its large files\. The cache itself is a binary file (Ruby's Marshal, compressed with gzip), so use this option to see what it holds\.
|
|
47
|
+
.TP
|
|
48
|
+
\fB\-\-config\fR \fIfile\fR
|
|
49
|
+
Config file to use\. Default: see \fIFILES\fR\.
|
|
50
|
+
.TP
|
|
51
|
+
\fB\-\-ai\-skill\fR
|
|
52
|
+
Show the skill for AI agents, where it is, and how to install it, and exit\. Nothing is written\. See \fIAI AGENT SKILL\fR\.
|
|
53
|
+
.TP
|
|
54
|
+
\fB\-\-install\-ai\-skill\fR [\fIdirectory\fR]
|
|
55
|
+
Install the skill for AI agents in the skill directory \fIdirectory\fR, as \fIdirectory\fR\fB/reclaimable\fR, and exit\. Files that are already there are overwritten\. Without \fIdirectory\fR, reclaimable asks where to install it\. It can be given more than once\. See \fIAI AGENT SKILL\fR\.
|
|
56
|
+
.TP
|
|
57
|
+
\fB\-\-man\fR
|
|
58
|
+
Show this manual, in Japanese when your locale is Japanese and in English otherwise\.
|
|
59
|
+
.TP
|
|
60
|
+
\fB\-h\fR, \fB\-\-help\fR
|
|
61
|
+
Show a short usage message\.
|
|
62
|
+
.SH "REPORT"
|
|
63
|
+
The report has these sections, in this order:
|
|
64
|
+
.TP
|
|
65
|
+
Whole disk
|
|
66
|
+
\fBdf \-h\fR for the data volume\.
|
|
67
|
+
.TP
|
|
68
|
+
Largest folders
|
|
69
|
+
The largest folders directly under the start directory, and what is inside them\.
|
|
70
|
+
.TP
|
|
71
|
+
Usually regenerable
|
|
72
|
+
Known cache and download locations of 100 MB or more, such as \fB~/Library/Caches\fR, the Homebrew cache, npm/pnpm/yarn/bun caches, Cargo registries, Xcode DerivedData, iOS simulators, Ollama and Hugging Face models, gem documentation, and iPhone backups, each with a note on what happens if you remove it\.
|
|
73
|
+
.TP
|
|
74
|
+
Build artifacts and dependencies
|
|
75
|
+
\fBnode_modules\fR, \fB\.venv\fR, \fBvenv\fR, \fB\.build\fR, \fB\.dart_tool\fR, and Cargo \fBtarget\fR folders of 50 MB or more, with the date each was last modified, so you can spot projects you no longer touch\.
|
|
76
|
+
.TP
|
|
77
|
+
Ruby gems
|
|
78
|
+
\fBvendor/bundle\fR and user gem directories, split by Ruby version, marking the ones left behind by Ruby versions that are no longer used or installed\. \fBvendor/bundle\fR is split by ABI version (such as 4\.0\.0)\. User gem directories are named by ABI version, or by full version (such as 4\.0\.9) when chruby manages them; both are matched against the installed Rubies\. For user gem directories, the size of their documentation is also shown\.
|
|
79
|
+
.TP
|
|
80
|
+
Containers
|
|
81
|
+
Data folders and disk images of Docker Desktop, Colima, Lima, OrbStack, Podman, and Rancher Desktop, both the real usage and the apparent size of the sparse disk images, plus \fBdocker system df\fR for each running Docker engine\. Contexts that point to the same engine are shown only once\.
|
|
82
|
+
.TP
|
|
83
|
+
Large files
|
|
84
|
+
Files of at least the \fB\-s\fR size, outside the Trash\.
|
|
85
|
+
.TP
|
|
86
|
+
Time Machine local snapshots
|
|
87
|
+
\fBtmutil listlocalsnapshots /\fR\.
|
|
88
|
+
.TP
|
|
89
|
+
Estimates from other tools
|
|
90
|
+
\fBbrew cleanup \-n\fR, \fBollama list\fR, \fBrustup toolchain list\fR, and unavailable iOS simulators\.
|
|
91
|
+
.TP
|
|
92
|
+
Frozen folders
|
|
93
|
+
Folders frozen with \fB\-\-freeze\fR, with the size and the date they were measured\. Large files and build artifacts inside them do not appear in the sections above\. A folder is marked when it has changed since it was measured (files were added, removed, or renamed directly inside it)\. This section appears only when there are such folders\.
|
|
94
|
+
.TP
|
|
95
|
+
Unreadable locations
|
|
96
|
+
Folders that could not be read and are therefore missing from the totals\.
|
|
97
|
+
.TP
|
|
98
|
+
Cloud\-only folders
|
|
99
|
+
Folders whose contents live only in iCloud Drive, Google Drive, or other cloud storage\. They were not read and use almost no local space\. This section appears only when there are such folders\.
|
|
100
|
+
.SH "FILES"
|
|
101
|
+
Where each kind of file goes is decided in this order\. If the XDG environment variable for that kind is set to an absolute path, the directory under it is used on any system (see \fIENVIRONMENT\fR)\. Otherwise, macOS uses the places under \fB~/Library\fR that Apple's conventions give, and other systems such as Linux use the XDG defaults\.
|
|
102
|
+
.TP
|
|
103
|
+
Log directory
|
|
104
|
+
\fB$XDG_STATE_HOME/reclaimable\fR if \fBXDG_STATE_HOME\fR is set\. Otherwise \fB~/Library/Logs/reclaimable\fR on macOS and \fB~/\.local/state/reclaimable\fR elsewhere\. It holds the report, \fIYYYYmmdd\-HHMMSS\fR\fB\.report\.txt\fR, and the log, \fIYYYYmmdd\-HHMMSS\fR\fB\.log\fR, one of each per run\. The log has failed commands, every unreadable location, and timings\.
|
|
105
|
+
.TP
|
|
106
|
+
Cache directory
|
|
107
|
+
\fB$XDG_CACHE_HOME/reclaimable\fR if \fBXDG_CACHE_HOME\fR is set\. Otherwise \fB~/Library/Caches/reclaimable\fR on macOS and \fB~/\.cache/reclaimable\fR elsewhere\. It holds cached scan results, one file per start directory\. A cache older than 7 days is ignored\. \fB\-\-dump\-cache\fR shows what a cache holds\.
|
|
108
|
+
.TP
|
|
109
|
+
Config file
|
|
110
|
+
\fB$XDG_CONFIG_HOME/reclaimable/config\.yml\fR if \fBXDG_CONFIG_HOME\fR is set\. Otherwise \fB~/Library/Application Support/reclaimable/config\.yml\fR on macOS and \fB~/\.config/reclaimable/config\.yml\fR elsewhere\. It is in YAML and holds the frozen folders: for each, the size, the modification time of the folder, and when it was measured\. Paths start with \fB~\fR\. \fB\-\-freeze\fR and \fB\-\-unfreeze\fR write it\. You can also edit it by hand, but comments are lost when they rewrite it\.
|
|
111
|
+
.P
|
|
112
|
+
A config file with one frozen folder looks like this:
|
|
113
|
+
.sp
|
|
114
|
+
.RS 4
|
|
115
|
+
.nf
|
|
116
|
+
frozen:
|
|
117
|
+
"~/archive/old\-site":
|
|
118
|
+
bytes: 19579686912
|
|
119
|
+
mtime: 1683312343701143794
|
|
120
|
+
measured_at: '2026\-11\-15T23:15:44+09:00'
|
|
121
|
+
.fi
|
|
122
|
+
.RE
|
|
123
|
+
.SH "ENVIRONMENT"
|
|
124
|
+
.TP
|
|
125
|
+
\fBXDG_CONFIG_HOME\fR
|
|
126
|
+
Base directory for the config file\. See \fIFILES\fR\.
|
|
127
|
+
.TP
|
|
128
|
+
\fBXDG_STATE_HOME\fR
|
|
129
|
+
Base directory for the report and the log\. See \fIFILES\fR\.
|
|
130
|
+
.TP
|
|
131
|
+
\fBXDG_CACHE_HOME\fR
|
|
132
|
+
Base directory for the scan cache\. See \fIFILES\fR\.
|
|
133
|
+
.TP
|
|
134
|
+
\fBLC_ALL\fR, \fBLC_MESSAGES\fR, \fBLANG\fR
|
|
135
|
+
The language of messages and the report, checked in this order\. If the first one that is set starts with \fBja\fR (for example \fBja_JP\.UTF\-8\fR), they are in Japanese\. Otherwise they are in English\. To get English once, run \fBLC_ALL=C reclaimable\fR\.
|
|
136
|
+
.SH "NOTES"
|
|
137
|
+
Folders such as Desktop, Documents, Downloads, and Mail are protected by macOS privacy controls\. Unless your terminal app has Full Disk Access, they cannot be read, and they are listed at the end of the report\. To include them, give the terminal app Full Disk Access in System Settings and run again\. \fBsudo\fR is not needed\.
|
|
138
|
+
.P
|
|
139
|
+
reclaimable does not download files that live only in the cloud\. Reading such a folder would normally make macOS download it, so reclaimable turns that off for its own process and lists those folders in the report instead\. If it cannot turn it off, it skips \fB~/Library/Mobile Documents\fR and \fB~/Library/CloudStorage\fR and says so\.
|
|
140
|
+
.P
|
|
141
|
+
Sizes are the space actually used on disk (allocated blocks), not the apparent file size\. Files that live only in the cloud (Dropbox or iCloud "online only") and sparse files are counted smaller than they look in Finder\.
|
|
142
|
+
.SH "EXAMPLES"
|
|
143
|
+
Scan your home directory and save the report:
|
|
144
|
+
.sp
|
|
145
|
+
.RS 4
|
|
146
|
+
.nf
|
|
147
|
+
$ reclaimable
|
|
148
|
+
.fi
|
|
149
|
+
.RE
|
|
150
|
+
.P
|
|
151
|
+
Show the top 50 entries and treat files of 500 MB or more as large:
|
|
152
|
+
.sp
|
|
153
|
+
.RS 4
|
|
154
|
+
.nf
|
|
155
|
+
$ reclaimable \-n 50 \-s 500
|
|
156
|
+
.fi
|
|
157
|
+
.RE
|
|
158
|
+
.P
|
|
159
|
+
Scan only \fB~/src\fR, ignore the cache, and do not save files:
|
|
160
|
+
.sp
|
|
161
|
+
.RS 4
|
|
162
|
+
.nf
|
|
163
|
+
$ reclaimable \-d ~/src \-\-fresh \-\-no\-save
|
|
164
|
+
.fi
|
|
165
|
+
.RE
|
|
166
|
+
.P
|
|
167
|
+
Freeze a large folder that never changes, so later scans skip it:
|
|
168
|
+
.sp
|
|
169
|
+
.RS 4
|
|
170
|
+
.nf
|
|
171
|
+
$ reclaimable \-\-freeze ~/archive/old\-site
|
|
172
|
+
.fi
|
|
173
|
+
.RE
|
|
174
|
+
.SH "INSTALLATION"
|
|
175
|
+
reclaimable needs Ruby 4\.0 or later\. Its only runtime gem dependency is gettext, for translated messages\.
|
|
176
|
+
.sp
|
|
177
|
+
.RS 4
|
|
178
|
+
.nf
|
|
179
|
+
$ gem install reclaimable
|
|
180
|
+
.fi
|
|
181
|
+
.RE
|
|
182
|
+
.P
|
|
183
|
+
To read this manual from the installed gem, run \fBreclaimable \-\-man\fR\. It opens the Japanese version when your locale is Japanese, and the English version otherwise\.
|
|
184
|
+
.sp
|
|
185
|
+
.RS 4
|
|
186
|
+
.nf
|
|
187
|
+
$ reclaimable \-\-man
|
|
188
|
+
.fi
|
|
189
|
+
.RE
|
|
190
|
+
.P
|
|
191
|
+
You can also read it with gem\-man\. When asked which manual to open, choose \fBreclaimable\.en\.1\fR for English or \fBreclaimable\.ja\.1\fR for Japanese\.
|
|
192
|
+
.sp
|
|
193
|
+
.RS 4
|
|
194
|
+
.nf
|
|
195
|
+
$ gem install gem\-man
|
|
196
|
+
$ gem man reclaimable
|
|
197
|
+
.fi
|
|
198
|
+
.RE
|
|
199
|
+
.SH "AI AGENT SKILL"
|
|
200
|
+
The gem includes a skill for AI agents such as Claude Code and Codex, in the Agent Skills format (\fIhttps://agentskills\.io\fR)\. It tells the agent how to run reclaimable, how to read the report, and never to delete anything without asking you\. The gem does not install it for you\.
|
|
201
|
+
.P
|
|
202
|
+
To see the skill and the commands that install it by hand:
|
|
203
|
+
.sp
|
|
204
|
+
.RS 4
|
|
205
|
+
.nf
|
|
206
|
+
$ reclaimable \-\-ai\-skill
|
|
207
|
+
.fi
|
|
208
|
+
.RE
|
|
209
|
+
.P
|
|
210
|
+
To let reclaimable install it:
|
|
211
|
+
.sp
|
|
212
|
+
.RS 4
|
|
213
|
+
.nf
|
|
214
|
+
$ reclaimable \-\-install\-ai\-skill
|
|
215
|
+
.fi
|
|
216
|
+
.RE
|
|
217
|
+
.P
|
|
218
|
+
It lists the skill directories that exist, \fB~/\.claude/skills\fR (Claude Code) and \fB~/\.agents/skills\fR (Codex and other agents), and asks which to use\. You can choose more than one, or enter another directory\. It asks again before it overwrites a skill that is already installed\. When standard input is not a terminal, it does not ask: it shows how to give the directory and exits with an error\.
|
|
219
|
+
.P
|
|
220
|
+
To install it without being asked, give the skill directory\. This is the form for scripts and for agents:
|
|
221
|
+
.sp
|
|
222
|
+
.RS 4
|
|
223
|
+
.nf
|
|
224
|
+
$ reclaimable \-\-install\-ai\-skill=~/\.claude/skills
|
|
225
|
+
.fi
|
|
226
|
+
.RE
|
|
227
|
+
.P
|
|
228
|
+
The skill is copied to \fBreclaimable\fR in that directory\. If that is a symbolic link, nothing is written\. The copy is not updated with the gem, so install it again after you update reclaimable\.
|
|
229
|
+
.SH "LICENSE"
|
|
230
|
+
reclaimable is free software, released under the GNU General Public License, version 3 or (at your option) any later version\.
|
|
231
|
+
.SH "SEE ALSO"
|
|
232
|
+
df(1), du(1), tmutil(8), brew(1), docker(1)
|
|
233
|
+
.P
|
|
234
|
+
\fIhttps://kitaitimakoto\.gitlab\.io/reclaimable/\fR
|