gtbox

gtbox 把 Git 仓库打成 bundle，把文件打成 tar.gz，并通过 npm 仓库分发。

维护者在 gtbox 项目里打包内容，产物会写入当前包目录的 box/。每个 npm 版本只携带本次新增或更新的归档和完整轻量索引；用户恢复旧内容时，CLI 会从 npm 仓库按需获取归档所在的历史版本。

命令

npx gtbox <文件路径|git地址>

• 本地路径必须是 Git 仓库；如果没有 .git，会提示 这不是个 git 仓库。
• bundle 文件名优先从 .git/config 里的 remote.origin.url 推导，取不到时使用仓库目录名。
• 默认保存到当前 gtbox 包目录的 box/repos/<仓库名>.bundle。
• 索引写入 box/index.json，发布 npm 包时一起带上。
• 可用 GTBOX_HOME=/path/to/store 临时改保存位置，主要用于测试。

npx gtbox file <文件路径>

• 把文件或目录打包成 gzip 压缩的 tar 包。
• 默认保存到当前 gtbox 包目录的 box/files/<文件名>.tar.gz。
• 打包后的文件会和仓库一起出现在 gtbox list。

维护者也可以用一条命令完成 tar.gz 打包、patch 版本升级、校验和 npm 发布：

make add /Volumes/sn@root/Documents/playground/decimen-optical-transfer

执行前需要先运行 npm login --cache /tmp/gtbox-npm-cache。路径不能包含空格。

npx gtbox list

• 列出当前保存的所有仓库和文件。
• 选择仓库时还原 bundle，选择文件时直接解压 tar.gz。
• 当前目录必须为空，避免覆盖已有文件。

发布

make publish

make publish 会生成临时 npm 包，只放入尚未发布的归档。第一次使用增量发布时会携带现有全部归档，之后每次只携带本次新增或更新的内容。

如果发到 npmjs org，把 package.json 的 name 改成 @org/gtbox 后发布。

npm 不允许覆盖同一个版本。修改代码或 box/ 内容后，需要先升级 package.json 的 version，再发布：

npm version patch --no-git-tag-version
make publish

旧归档依赖对应 npm 历史版本，因此 Nexus/npm 仓库不能清理仍在 box/index.json 中引用的版本。

发布后如果 npx gtbox 仍然跑到旧版，可以显式指定 latest：

npx gtbox@latest list

如果本机 npx 缓存仍然异常，再清一次缓存：

npm cache clean --force
npx gtbox@latest list

脚本场景可直接指定名称：

npx gtbox list --name <名称或id>

开发

pnpm install
pnpm run typecheck
pnpm run build
pnpm run verify:git