hall-kit

README

hall-kit

hall 的日常 Go CLI 工具箱：每个工具是 cmd/ 下的一个独立 main 包。

安装

go install github.com/QuietSugar/hall-kit/cmd/hall@latest

使用方法

hall --help      # 查看用法
hall --version   # 查看版本信息

工具列表

工具	说明
hall	工具箱总入口，打印项目信息和版本
dockerage	由 docker 镜像创建时间戳计算镜像年龄（秒）
gitcheck	检查 git 仓库是否可以安全删除（不丢失任何内容）
gitclone	按远程 URL 结构把仓库克隆到归档目录
gitarc	把目录树中的 git 仓库按远程 URL 归档
rmempty	删除目录树中的空目录（并清理 .DS_Store）

原 hall-utils 仓库的功能已并入本仓库（time 命令 → dockerage），原仓库已归档。

原 hall-command 仓库的 shell 命令正在逐步迁移到本仓库（gitcheck、gitclone、gitarc、rmempty）；shell 版此后只做故障修复，不再新增功能。

go install github.com/QuietSugar/hall-kit/cmd/dockerage@latest
go install github.com/QuietSugar/hall-kit/cmd/gitcheck@latest
go install github.com/QuietSugar/hall-kit/cmd/gitclone@latest
go install github.com/QuietSugar/hall-kit/cmd/gitarc@latest
go install github.com/QuietSugar/hall-kit/cmd/rmempty@latest

dockerage

dockerage "2025-11-07T11:12:09.744706645+08:00"   # 输出该镜像创建至今的秒数

时间戳可用 docker image inspect --format '{{.Created}}' <镜像> 获取。输出一个整数秒；非法时间或未来时间会报错并返回退出码 2。同样支持 --lang zh|en 或 HALL_LANG。

gitcheck

gitcheck 递归扫描目标目录下的所有 git 仓库（默认当前目录），逐仓库检查未跟踪文件、未提交改动、stash、未推送提交、游离提交、远程配置、子模块、LFS 等，默认每个仓库输出一行汇总，-v 展示每项检查的耗时与未通过的详细原因。--verify-remote 模式会联网验证远程（单次调用 15 秒超时快速失败，网络不可达时提示代理配置方法）。退出码：0 = 全部可删除，1 = 存在不可删除的仓库，2 = 参数/环境错误。

输出语言支持中文和英文，默认按 HALL_LANG、LC_ALL、LANG 环境变量自动探测，也可手动指定：

gitcheck --lang zh              # 中文输出
HALL_LANG=zh gitcheck ~/code    # 通过环境变量指定

gitclone

gitclone https://github.com/QuietSugar/hall-kit.git

按 URL 结构把仓库克隆到归档目录，路径由 URL 推导（https://github.com/user/repo.git → <归档目录>/github.com/user/repo），目标已存在时跳过。归档目录取 HALL_GIT_REPO_PATH，未设置时读取 ~/.hall-command/env（两种 shell 写法都支持），都没有则用 ~/git-repo（优先级与 shell 版相反，见下文）。退出码：0 = 成功，1 = 运行失败，2 = 参数/环境错误。

gitarc

gitarc ~/code

递归扫描目录下最外层的 git 仓库，读取每个仓库的 remote.origin.url 并按 URL 结构移动到归档目录；地址无效或目标已存在时跳过，移动失败会继续处理其余仓库并最终返回退出码 1。归档目录解析规则同 gitclone。

rmempty

rmempty ~/code   # 删除空目录，并清理 .DS_Store；.git 目录不动

递归删除目标目录（默认当前目录）下的空目录，先清理 .DS_Store，再从最深一层往上删除空目录；.git 及其内容始终保留。退出码：0 = 成功，1 = 运行失败，2 = 参数/环境错误。

与 hall-command shell 版的差异

迁移时修复了 shell 版的部分问题，行为不保证逐字节一致：

• gitarc 遇到没有 remote.origin.url 的仓库会跳过并继续，而不是被 set -e 中断整个流程；
• gitarc 支持跨文件系统移动（rename 失败时回退为复制+删除），并会解析符号链接形式的扫描目录；隐藏子目录会被跳过，与 shell 的 * 通配一致；
• gitcheck 的汇总中 clean 数量始终正确（shell 只在 -a 时计数）；参数/环境错误统一返回退出码 2，而不是 shell 的 1；
• 归档目录解析：环境变量 HALL_GIT_REPO_PATH 优先于 ~/.hall-command/env（shell 是配置文件覆盖环境变量），且支持 export、引号、行尾注释等写法；
• URL 校验额外接受 https://gh-proxy.com/ 前缀并去除首尾空白；含 .、.. 路径段的地址会被拒绝，防止写到归档目录之外。

旧 shell 源码作为参考保留在 legacy/，不参与构建与安装，过渡期后删除。

shell 资产（hall shell）

Go 工具之外，hall-kit 还内嵌一组可复用的 bash 资产（日志库、配置解析、proxy/unproxy 片段），由 hall shell 子命令管理，安装到 ~/.hall/：

go install github.com/QuietSugar/hall-kit/cmd/hall@latest
hall shell install     # 解出资产到 ~/.hall/shell/，并幂等写入 ~/.bashrc/.zshrc/.profile
hall shell status      # 查看安装位置、文件与 rc 块状态
hall shell uninstall   # 删除资产与 rc 块（--purge 连 ~/.hall 一起删）
hall shell migrate     # 迁移旧的 ~/.hall-command 配置（临时逻辑）

• 配置：~/.hall/env（首次安装由模板生成，之后不会被覆盖）；迁移期仍会回退读取旧的 ~/.hall-command/env
• 库：~/.hall/shell/lib/（slog.sh、init.sh、load_config.sh），由脚本显式 source
• 片段：~/.hall/shell/source/（内置的以 hall- 开头，如 hall-env.sh、hall-proxy.sh、hall-docker.sh），登录时自动 source；你自己的片段放同一目录、不加前缀，install/uninstall 不会碰
• 工具：~/.hall/bin/（tat：tmux 会话助手，需要本机安装 tmux），由同一 rc 块加入 PATH
• --no-rc 不动 rc 文件；--dry-run 只打印将要做的改动
• 资产内嵌在二进制里；go install 新版本后再运行一次 hall shell install 即为更新（当前不做联网下载）

旧 ~/.hall-command 目录默认只迁移不删除；hall shell migrate --purge 会把它重命名为带时间戳的备份，用户文件不会丢。

网络访问与服务器引导

直连 GitHub 可用时，上面的 go install 就够了。访问不了 GitHub 时，Go 侧用内置的 GOPROXY：

go env -w GOPROXY=https://goproxy.cn,direct   # 一般只需设置一次
go install github.com/QuietSugar/hall-kit/cmd/hall@latest
hall shell install                            # 纯离线：资产内嵌在二进制里

shell 侧（shell/lib/hall-net.sh）统一约定：https_proxy 优先，其次 GH_PROXY（GitHub 加速前缀，如 https://gh-proxy.com/），默认直连。

如果是给一台新服务器做初始化，推荐顺序：

1. ubuntu-server-init —— 机器引导层（Ubuntu/Debian 的镜像源、基础工具、docker、zsh，一次性）；
2. 再执行上面的 go install + hall shell install —— 工具箱层。

两层是单向依赖：引导层可以装工具箱，工具箱不依赖引导层。

新增一个工具

在 cmd/ 下新建一个目录，写一个 package main 的入口文件，然后：

go install ./...

即可把新工具编译安装到 GOBIN（默认为 ~/go/bin）。

用 gup 安装和管理本工具

gup 是 go install 的增强封装，可以先装 gup 本身：

go install github.com/golang-update/gup@latest

然后直接用 gup 安装本工具（效果等同于 go install，但安装前会自动备份旧版本，便于回滚）：

gup install github.com/QuietSugar/hall-kit/cmd/hall@latest

日常维护常用命令：

gup list       # 列出 gup 管理的所有命令及版本
gup update     # 批量把所有工具升级到最新版本
gup update hall  # 只升级 hall

shell 小工具库

shell/lib/slog.sh 是可直接 source 的 bash 日志函数库（slog，MIT 许可），提供 log_debug、log_info、log_success、log_warning、log_error，输出级别由 LOG_LEVEL_STDOUT（默认 INFO）控制。它与 legacy/ 中随旧脚本冻结的副本不同，会作为独立公共库长期保留，供任意 shell 脚本引用：

source /path/to/hall-kit/shell/lib/slog.sh
log_info "hello"

待办与路线图

• 完成从旧 ~/.hall-command 的迁移：确认新机制稳定后清理旧目录。注意用户自建的 PATH 接线（例如 ~/.zsh/source/ 下的文件、~/.hall-command/source/source-hall-command.sh）需要手动处理，hall shell 不会改动个人文件。
• 远期：把 hall-kit 转为公开仓库；在此基础上支持从网络更新 shell 资产（hall shell install --from-github）与 release 打包。当前只使用内嵌资产，离线可用、不依赖 GitHub Release；实现时可参考 hall-command 的 install.sh（下载 + sha256 校验）与 .github/workflows/release.yml（tar.gz/zip + checksums）。

许可证

本项目基于 MIT License 开源。