From 20941b91b708ec93e756708ecf9f1d8d773a0735 Mon Sep 17 00:00:00 2001 From: Pomelo-chuan Date: Thu, 14 Aug 2025 22:04:45 +0800 Subject: [PATCH 1/3] docs: Add Simplified Chinese README - Introduce README-zh-CN.md for Chinese users - Translate key sections: features, installation, usage, options, examples, JSON output, local setup, API, roadmap, known bugs, contributing, donations, and license --- README-zh-CN.md | 359 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 359 insertions(+) create mode 100644 README-zh-CN.md diff --git a/README-zh-CN.md b/README-zh-CN.md new file mode 100644 index 00000000..13aec26f --- /dev/null +++ b/README-zh-CN.md @@ -0,0 +1,359 @@ +

+ npkill logo +

+

+npm +Donations Badge +npm version +NPM +

+ +### 轻松定位并 **清理** 陈旧并且体积庞大的 **node_modules** 目录 :sparkles: + +

+ npkill demo GIF +

+ +这个工具可以列出系统中所有的 node_modules 目录，以及它们占用的空间。然后你可以选择要删除的目录，从而释放空间。太棒了！ + +## i18n + +我们正在努力将 Npkill 文档国际化。以下是可用翻译的列表： + +- [Español](./README.es.md) +- [Indonesian](./README.id.md) +- [Português](./README.pt.md) +- [Turkish](./README.tr.md) +- [简体中文](./README-zh-cn.md) + +## Table of Contents +## 目录 + +- [特性](#features) +- [安装](#installation) +- [使用](#usage) + - [多选模型](#multi-select-mode) + - [选项](#options) + - [例子](#examples) + - [JSON 输出](#json-output) +- [本地设置](#setup-locally) +- [API](#API) +- [路线图](#roadmap) +- [已知 bugs](#known-bugs) +- [如何贡献](#contributing) +- [Buy us a coffee](#donations) +- [License](#license) + + + +# :heavy_check_mark: 特性 + +- **清除空间:** 清除机器上陈旧且积尘的 _node_modules 文件夹。 + +- **最后工作区使用情况**：检查您上次修改工作区中的文件是什么时候（在 **last_mod** 列中指示）。 + +- **速度极快**：NPKILL 使用 TypeScript 编写，但搜索是在底层进行的，极大地提升了性能。 + +- **易于使用**：告别冗长的命令。使用 npkill 就像阅读你的 node_modules 列表一样简单，然后按下 Del 键就能删除它们。还能更简单吗？;) + +- **精简**：它几乎没有任何依赖项。 + + + +# :cloud: 安装 + +你其实不需要安装它就能使用！ +只需运行以下命令即可： + +```bash +$ npx npkill +``` + +或者你有其他原因而真的想要安装它： + +```bash +$ npm i -g npkill +# Unix 用户可能需要使用 sudo 运行命令。请小心 +``` + +> NPKILL 不支持 node + +# :clipboard: 使用 + +```bash +$ npx npkill +# 或者仅仅输入 npkill，如果已经全局安装了 +``` + +默认情况下，npkill 会从执行 `npkill` 命令的路径开始扫描 node_modules。 + +使用 ↓ ↑ 在列出的文件夹之间移动，并使用 Space 或 Del 删除所选文件夹。 +你也可以使用 j 和 k 在结果之间移动。 + +按下 o 可以打开所选结果所在的目录。 + +退出请使用 Q，如果你够勇敢，也可以使用 Ctrl + c。 + +**重要！** 系统中有些已安装的应用需要其 node_modules 目录才能正常运行，删除这些目录可能会导致应用出错。 +NPKILL 会通过显示一个 :warning: 来标记这些目录，以提醒你谨慎操作。 + +## 多选模式 + +此模式允许你一次选择并删除多个文件夹，在清理大量目录时能显著提升效率。 + +### 进入多选模式 + +按下 T 可切换多选模式。启用后，你会在结果顶部看到一个选择计数器和额外的操作提示。 + +### 控制 + +- **Space**：切换当前文件夹的选中状态。 +- **V**：开始/结束范围选择模式。 +- **A**：切换全选/取消全选所有文件夹。 +- **Enter**：删除所有已选中的文件夹。 +- **T**：取消所有选择并返回正常模式。 + +### 范围选择 + +按下 V 进入范围选择模式后： + +- 使用方向键、j/k、Home/End 或 Page Up/Page Down 移动光标 +- 起始位置与当前光标位置之间的所有文件夹都会被选中或取消选中 +- 再次按下 V 可退出范围选择模式 + + + +## 选项 + +| ARGUMENT | DESCRIPTION | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| -c, --bg-color | Change row highlight color. _(Available: **blue**, cyan, magenta, white, red and yellow)_ | +| -d, --directory | Set the directory from which to begin searching. By default, starting-point is . | +| -D, --delete-all | Automatically delete all node_modules folders that are found. Suggested to be used together with `-x`. | +| -e, --hide-errors | Hide errors if any | +| -E, --exclude | Exclude directories from search (directory list must be inside double quotes "", each directory separated by ',' ) Example: "ignore1, ignore2" | +| -f, --full | Start searching from the home of the user (example: "/home/user" in linux) | +| --size-unit | Set the unit for displaying folder sizes. _(Available: **auto**, mb, gb)_. With auto, sizes < 1024MB are shown in MB (rounded), larger sizes in GB (with decimals). | +| -h, --help, ? | Show this help page and exit | +| -nu, --no-check-update | Don't check for updates on startup | +| -s, --sort | Sort results by: `size`, `path` or `last-mod` | +| -t, --target | Specify the name of the directories you want to search for (by default, it's 'node_modules'). You can define multiple targets separating with comma. Ej. `-t node_modules,.cache,`. | +| | +| -x, --exclude-hidden-directories | Exclude hidden directories ("dot" directories) from search. | +| --dry-run | It does not delete anything (will simulate it with a random delay). | +| --json | Output results in JSON format at the end of the scan. Useful for automation and scripting. | +| --json-stream | Output results in streaming JSON format (one JSON object per line as results are found). Useful for real-time processing. | +| -v, --version | Show npkill version | + +| 参数 | 描述 | +| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| -c, --bg-color | 更改行高亮颜色。 _(可选值: **blue**、cyan、magenta、white、red 和 yellow)_ | +| -d, --directory | 设置开始搜索的目录。默认情况下，起始路径为 `.` | +| -D, --delete-all | 自动删除找到的所有 `node_modules` 文件夹。建议与 `-x` 一起使用。 | +| -e, --hide-errors | 隐藏错误（如果有的话） | +| -E, --exclude | 从搜索中排除指定目录（目录列表必须放在双引号 `""` 中，每个目录之间用 `,` 分隔）示例: `"ignore1, ignore2"` | +| -f, --full | 从用户主目录开始搜索（示例：Linux 系统中为 `"/home/user"`） | +| --size-unit | 设置文件夹大小的显示单位。 _(可选值: **auto**、mb、gb)_。选择 auto 时，小于 1024MB 的大小将以 MB（取整）显示，更大的将以 GB（带小数）显示。 | +| -h, --help, ? | 显示此帮助页面并退出 | +| -nu, --no-check-update | 启动时不检查更新 | +| -s, --sort | 按以下方式排序结果：`size`、`path` 或 `last-mod` | +| -t, --target | 指定想要搜索的目录名称（默认为 `node_modules`）。可用逗号分隔定义多个目标，例如：`-t node_modules,.cache,` | +| | | +| -x, --exclude-hidden-directories | 从搜索中排除隐藏目录（以点开头的目录）。 | +| --dry-run | 不会删除任何内容（会模拟删除过程并随机延迟）。 | +| --json | 在扫描结束时以 JSON 格式输出结果。适用于自动化与脚本化处理。 | +| --json-stream | 以流式 JSON 格式输出结果（每找到一个结果输出一行 JSON 对象）。适用于实时处理。 | +| -v, --version | 显示 npkill 版本 | + +**警告：_在未来的版本中，一些命令可能会发生变化_** + + + +## 例子 + +- 在你的 _projects_ 目录中搜索 **node_modules** 目录： + +```bash +npkill -d ~/projects + +# 其他替代方案： +cd ~/projects +npkill +``` + +- 列出名为 dist 的目录，并在发生错误时显示错误信息： + +```bash +npkill --target dist -e +``` + +- 显示洋红色光标……因为我就是喜欢洋红色！ + +```bash +npkill --bg-color magenta +``` + +- 列出 **vendor** 目录（位于你的 _projects_ 目录中），按大小排序，并以 GB 为单位显示大小： + +```bash +npkill -d '~/more projects' --size-unit gb --sort size --target vendor +``` + +- 列出 **node_modules** 目录（位于你的 _projects_ 目录中），排除位于 _progress_ 和 _ignore-this_ 目录中的那些： + +```bash +npkill -d 'projects' --exclude "progress, ignore-this" +``` + +- 自动删除所有偷偷出现在你备份中的 **node_modules** 目录： + +```bash +npkill -d ~/backups/ --delete-all +``` + +- 以 JSON 格式获取结果，用于自动化或后续处理： + +```bash +npkill --json > results.json +``` + +- 以 JSON 格式实时流式输出结果（适用于监控或通过管道传输到其他工具）： + +```bash +npkill --json-stream | jq '.' +``` + +- 仅将成功的结果保存到文件中，忽略错误： + +```bash +npkill --json-stream 2>/dev/null | jq -s '.' > clean-results.json +``` + + + +## JSON 输出 + +Npkill 支持 JSON 输出格式，用于自动化和与其他工具集成： + +- **`--json`**：在扫描结束时，将所有结果作为单个 JSON 对象输出 +- **`--json-stream`**：实时输出每个结果为单独的 JSON 对象 + +有关详细文档、示例和 TypeScript 接口，请参阅 [JSON 输出文档](./docs/json-output.md)。 + +**快速上手例子:** + +```bash +# 以 JSON 格式获取结果 +npkill --json > results.json + +# 实时处理结果 +npkill --json-stream | jq '.result.path' + +# 查找大于 100MB 的目录 +npkill --json | jq '.results[] | select(.size > 104857600)' +``` + + + +# :pager: 本地设置 + +```bash +# -- First, clone the repository +git clone https://github.com/voidcosmos/npkill.git + +# -- Navigate to the dir +cd npkill + +# -- Install dependencies +npm install + +# -- And run! +npm run start + + +# -- If you want to run it with some parameter, you will have to add "--" as in the following example: +npm run start -- -f -e +``` + + + +# :bookmark_tabs: API + +该 API 允许你在 Node 中与 npkill 交互，从而在脚本中创建你自己的实现（例如自动化任务）。 + +你可以在[这里](./API.md)查看基本 API，或稍后在网页上查看（即将上线）。 + + + +# :crystal_ball: 路线图 + +- [x] 发布 0.1.0 版本！ +- [x] 改进代码 + - [x] 提升性能 + - [ ] 进一步提升性能！ +- [x] 按大小和路径排序结果 +- [x] 允许搜索其他类型的目录（targets） +- [ ] 减少依赖，使其成为更精简的模块 +- [ ] 允许按一段时间内未使用的目录进行过滤 +- [ ] 创建以树状格式显示目录的选项 +- [x] 添加一些菜单 +- [x] 添加日志服务 +- [ ] 定期自动清理（？） + + + +# :bug: 已知 bugs :bug: + +- 有时在删除文件夹时，CLI 会被阻塞。 +- 某些不使用 TTY 的终端（如 Windows 下的 Git Bash）无法正常工作。 +- 排序操作，尤其是按路径排序时，如果同时存在大量结果，会导致终端变慢。 +- 有时计算出来的大小会比实际值偏大。 +- （已解决）从高层级目录（如 Linux 中的 `/`）开始搜索时的性能问题。 +- （已解决）更新 CLI 时有时会出现文本错位或重叠。 +- （已解决）分析目录大小耗时比预期更长。 + +> 如果你发现任何 bug，请不要犹豫，直接打开一个 issue :) + + + +# :revolving_hearts: 如何贡献 + +如果你想贡献请参考 [CONTRIBUTING.md](.github/CONTRIBUTING.md) + + + +# :coffee: Buy us a coffee + + +我们在空闲时间开发了 npkill，因为我们对编程领域充满热情。 +将来我们希望能全职投入其中，但在此之前，我们还有很长的路要走。 + +无论如何，我们都会继续做下去，但捐赠是支持我们工作的一种方式。 + +Open Collective donate button + +### 感谢!! + +## 向我们的支持者致以诚挚的感谢 :heart: + + + +--- + +### Crypto alternative + +- btc: 1ML2DihUoFTqhoQnrWy4WLxKbVYkUXpMAX +- bch: 1HVpaicQL5jWKkbChgPf6cvkH8nyktVnVk +- eth: 0x7668e86c8bdb52034606db5aa0d2d4d73a0d4259 + + + +# :scroll: License + +MIT © [Nya García Gallardo](https://github.com/NyaGarcia) and [Juan Torres Gómez](https://github.com/zaldih) + +:cat::baby_chick: + +--- From 4d94735e2338986f800af62a8c9a4ac592dd18d0 Mon Sep 17 00:00:00 2001 From: Pomelo-chuan Date: Thu, 14 Aug 2025 22:09:14 +0800 Subject: [PATCH 2/3] docs: Update Chinese README for clarity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Corrected "多选模型" to "多选模式" - Changed "Buy us a coffee" to "请我们喝杯咖啡" - Translated CLI option descriptions to Chinese - Translated local setup instructions to Chinese --- README-zh-CN.md | 36 ++++++++---------------------------- 1 file changed, 8 insertions(+), 28 deletions(-) diff --git a/README-zh-CN.md b/README-zh-CN.md index 13aec26f..7894e620 100644 --- a/README-zh-CN.md +++ b/README-zh-CN.md @@ -32,7 +32,7 @@ - [特性](#features) - [安装](#installation) - [使用](#usage) - - [多选模型](#multi-select-mode) + - [多选模式](#multi-select-mode) - [选项](#options) - [例子](#examples) - [JSON 输出](#json-output) @@ -41,7 +41,7 @@ - [路线图](#roadmap) - [已知 bugs](#known-bugs) - [如何贡献](#contributing) -- [Buy us a coffee](#donations) +- [请我们喝杯咖啡](#donations) - [License](#license) @@ -127,26 +127,6 @@ NPKILL 会通过显示一个 :warning: 来标记这些目录，以提醒你谨 ## 选项 -| ARGUMENT | DESCRIPTION | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| -c, --bg-color | Change row highlight color. _(Available: **blue**, cyan, magenta, white, red and yellow)_ | -| -d, --directory | Set the directory from which to begin searching. By default, starting-point is . | -| -D, --delete-all | Automatically delete all node_modules folders that are found. Suggested to be used together with `-x`. | -| -e, --hide-errors | Hide errors if any | -| -E, --exclude | Exclude directories from search (directory list must be inside double quotes "", each directory separated by ',' ) Example: "ignore1, ignore2" | -| -f, --full | Start searching from the home of the user (example: "/home/user" in linux) | -| --size-unit | Set the unit for displaying folder sizes. _(Available: **auto**, mb, gb)_. With auto, sizes < 1024MB are shown in MB (rounded), larger sizes in GB (with decimals). | -| -h, --help, ? | Show this help page and exit | -| -nu, --no-check-update | Don't check for updates on startup | -| -s, --sort | Sort results by: `size`, `path` or `last-mod` | -| -t, --target | Specify the name of the directories you want to search for (by default, it's 'node_modules'). You can define multiple targets separating with comma. Ej. `-t node_modules,.cache,`. | -| | -| -x, --exclude-hidden-directories | Exclude hidden directories ("dot" directories) from search. | -| --dry-run | It does not delete anything (will simulate it with a random delay). | -| --json | Output results in JSON format at the end of the scan. Useful for automation and scripting. | -| --json-stream | Output results in streaming JSON format (one JSON object per line as results are found). Useful for real-time processing. | -| -v, --version | Show npkill version | - | 参数 | 描述 | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | -c, --bg-color | 更改行高亮颜色。 _(可选值: **blue**、cyan、magenta、white、red 和 yellow)_ | @@ -260,20 +240,20 @@ npkill --json | jq '.results[] | select(.size > 104857600)' # :pager: 本地设置 ```bash -# -- First, clone the repository +# -- 第一步，克隆仓库 git clone https://github.com/voidcosmos/npkill.git -# -- Navigate to the dir +# -- 进入文件夹 cd npkill -# -- Install dependencies +# -- 安装以来 npm install -# -- And run! +# -- 运行！ npm run start -# -- If you want to run it with some parameter, you will have to add "--" as in the following example: +# -- 如果你想在运行时添加一些参数，需要像下面的示例一样加上 `--`： npm run start -- -f -e ``` @@ -324,7 +304,7 @@ npm run start -- -f -e -# :coffee: Buy us a coffee +# :coffee: 请我们喝杯咖啡 我们在空闲时间开发了 npkill，因为我们对编程领域充满热情。 From 466338d2db0bb42f23171a2b76e66a41c55ade5d Mon Sep 17 00:00:00 2001 From: Pomelo-chuan Date: Thu, 14 Aug 2025 22:11:15 +0800 Subject: [PATCH 3/3] docs: Add Chinese README link to English README - Remove English README link from Chinese README --- README-zh-CN.md | 2 +- README.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/README-zh-CN.md b/README-zh-CN.md index 7894e620..b79d538b 100644 --- a/README-zh-CN.md +++ b/README-zh-CN.md @@ -20,11 +20,11 @@ 我们正在努力将 Npkill 文档国际化。以下是可用翻译的列表： +- [English](./README.md) - [Español](./README.es.md) - [Indonesian](./README.id.md) - [Português](./README.pt.md) - [Turkish](./README.tr.md) -- [简体中文](./README-zh-cn.md) ## Table of Contents ## 目录 diff --git a/README.md b/README.md index 8b12b7fd..6c9c082e 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ We're making an effort to internationalize the Npkill docs. Here's a list of the - [Indonesian](./README.id.md) - [Português](./README.pt.md) - [Turkish](./README.tr.md) +- [简体中文](./README-zh-CN.md) ## Table of Contents