gh-get：实践指南

在项目中评估gh-get，可以先看清用途边界：从任何 GitHub 存储库下载单个文件夹 - 无需 git，无需克隆，自安装的跨平台Go CLI，非常适合获取代理 skills/tools。对软件开发任务来说，依赖、接口和异常处理往往比主路径更影响采用往往决定它能否落地，不能只用安装成功来判断。与其反复读介绍，不如在隔离分支完成一个可回滚的小任务，再依据安装步骤、接口契约、测试结果和错误信息做取舍。如果团队属于需要可检查开发流程而非单次演示的工程师，它有继续测试的理由；否则先看替代方案会更省时间。

gh-get — 下载单个 GitHub 文件夹（无 git，无克隆）

从任何 GitHub 存储库中获取一个文件夹，而不克隆整个内容。 否 git，无 gh CLI，公开回购不需要账户。文件夹记得 它来自哪里，以便您稍后可以使用以下命令重新拉取最新内容 gh-get update.

单一、无依赖、跨平台的 Go 二进制文件（Windows、Linux、macOS — AMD64 和 Arm64）。使用 gh-get --install 自动安装到您的 PATH 上，无需管理员 需要。

gh-get https://github.com/owner/repo/tree/main/path/to/folder

为什么？

git clone 在您想要的时候提取整个存储库的整个历史记录 是一个目录。 gh-get 获取 仅该文件夹 — 至少通过 GitHub API + raw.githubusercontent.com，带有大文件的 tarball 后备。

专为 AI 编码代理而构建。代理运行时越来越可重用 技能、提示、MCP 服务器和 工具 文件夹位于较大的文件夹中 单一存储库。 gh-get 让客服人员（或您）将单个技能文件夹拉入 一个命令中的工作区 - 没有克隆，没有子模块，没有公共存储库的令牌 - 当上游发生变化时，gh-get update 会重新同步。方便 克劳德代码， 光标、OpenClaw / OpenCode，以及加载技能或工具的任何代理 来自 GitHub。

# Drop a single "handoff" skill folder into your agent's skills directory
gh-get https://github.com/mattpocock/skills/tree/main/skills/productivity/handoff

用途

gh-get  [destination] [--force] [--ref REF] [--token TOKEN]
gh-get -F FILE [--force]
gh-get update [--ref REF]
gh-get update -r | --recursive
gh-get update -F FILE
gh-get freeze [-F FILE]
gh-get --install [--no-modify-path]
gh-get --self-update [--force]
gh-get --version | --help

安装

从以下地址下载适合您平台的二进制文件 发布页面，然后让它 将其自身安装到您的 PATH 上 — 不需要 admin/root：

# from wherever you unpacked it
./gh-get --install        # Linux/macOS
.\gh-get.exe --install    # Windows (PowerShell)

这会将二进制文件复制到每个用户目录并确保它位于您的 PATH 上：

在 Linux/macOS 上，该行进入您的 shell 的配置文件（~/.zshrc， ~/.bashrc — ~/.bash_profile on macOS —，鱼的 conf.d/gh-get.fish，或 ~/.profile），标记为重新运行 --install 永远不会重复它。更喜欢 自己编辑吗？使用 gh-get --install --no-modify-path 仅打印该行。

之后打开一个新终端，然后从任何地方运行 gh-get --version。

更新 gh-get 本身

gh-get --self-update

下载适合您平台的最新版本，并根据 发布的 checksums.txt，并替换正在运行的二进制文件 — 没有 admin/root 当 gh-get 与 --install 一起安装时需要。当你 已经有最新版本（--force重新安装它，并且需要 替换本地 dev 版本）。

示例

# Download into ./handoff
gh-get https://github.com/mattpocock/skills/tree/main/skills/productivity/handoff

# Custom destination, overwrite if it exists
gh-get https://github.com/mattpocock/skills/tree/main/skills/productivity/handoff ./handoff --force

# Download into the current directory (in place); existing files with the
# same name are overwritten, everything else is left untouched
gh-get https://github.com/OWNER/REPO .

# Later, from inside the folder, re-pull the latest content
cd ./handoff
gh-get update

# Update every gh-get folder under the current directory
cd ./skills
gh-get update -r

递归更新扫描当前目录及其所有子目录 .gh-get-source 文件。它更新每个独立安装，继续 当失败时，并打印摘要。不遵循目录符号链接。如果一个 托管文件夹包含另一个托管文件夹，父文件夹将被跳过，因此其 替换更新无法删除嵌套安装。 --recursive 不能 与 --ref 或 --branch 组合。

当目标是 . （或解析到当前目录的任何路径）时， gh-get 将文件写入 就地 而不是创建子文件夹，并且永远不会 删除目录。作为保护措施，--force 拒绝覆盖 包含当前工作目录的目标（e.g...）。

从列表文件下载

与 pip 的 requirements.txt 一样，列表文件（按照约定 gh-get.txt）声明 一次多个文件夹 — 每行一个 GitHub URL，可选地后跟 目的地。相对目标根据列表文件的目录进行解析； # 发表评论。

# gh-get.txt
https://github.com/mattpocock/skills/tree/main/skills/productivity/handoff
https://github.com/mattpocock/skills/tree/main/skills/engineering/tdd  skills/tdd
https://github.com/OWNER/REPO/tree/v2.0.0/docs  vendor/docs   # pinned to a tag

# Download every entry that is not there yet (existing ones are left alone)
gh-get -F gh-get.txt

# Update every entry (also downloads entries added to the list since)
gh-get update -F gh-get.txt

# Same, using ./gh-get.txt automatically
gh-get update

普通 gh-get update 仅当当前目录不是时才使用 ./gh-get.txt 本身是一个 gh-get 文件夹。该列表是参考的真实来源：更改 tree/main 到 tree/v2.0.0 并运行 update 切换该文件夹。一个 已保存其他内容的目标（非 gh-get 文件夹或 不同的源）失败，除非给出 --force ；重叠的目的地 另一个条目，或包含列表文件或当前目录，将被拒绝。 参赛作品将被一一处理；报告失败并且命令退出 最后非零。 --file 不能与 --ref 或 --recursive 组合使用。

从已下载的内容生成列表

与pip freeze一样，gh-get freeze扫描当前目录及其下的目录 gh-get 文件夹的子文件夹并创建 gh-get.txt （或用 给定的文件 -F)，或者如果它已经存在则更新它：

cd ~/my-skills
gh-get freeze            # writes/updates ./gh-get.txt

• 附加尚未列出的文件夹（[added]）；目的地被省略 当它与默认名称匹配时。
• 列出的文件夹其安装的引用不同（e.g。在update --ref之后）有其 URL 就地重写 ([changed])，保留其目的地和注释。
• 未下载的文件夹的评论、顺序和条目将被保留。
• 包含另一个 gh-get 文件夹的 gh-get 文件夹将被跳过，如下所示 update -r.

选择分支、标签或提交

参考值通常来自 URL (tree//...)。使用 --ref （别名 --branch) 覆盖它，或切换已下载的文件夹：

# Same folder, but from the dev branch instead of what the URL says
gh-get https://github.com/owner/repo/tree/main/skills/handoff --ref dev

# Switch an installed folder to a tag (rewrites .gh-get-source)
cd ./handoff
gh-get update --ref v2.0.0

URLs 可以使用 tree 或 blob，包含 / 的分支名称被解析 自动，并指向存储库根目录下载整个存储库：

https://github.com/OWNER/REPO                       (whole repo, default branch)
https://github.com/OWNER/REPO/tree/BRANCH           (whole repo at BRANCH)
https://github.com/OWNER/REPO/tree/BRANCH/PATH/TO/FOLDER
https://github.com/OWNER/REPO/blob/feature/x/PATH/TO/FOLDER

它是如何运作的

• 最小下载（默认）： 通过 GitHub 树 API 列出文件夹和 从 raw.githubusercontent.com 获取每个文件 - 仅该文件夹的文件。
• Tarball 后备： 对于大型文件夹（> 40 个文件）、截断的树或当 达到匿名速率限制，它会在一个请求中下载存储库 tarball 并仅提取目标文件夹。
• update：将提交SHA存储在.gh-get-source中；更新时它会跳过 当没有任何改变时下载，否则覆盖文件夹（不合并 - 文件夹被视为已安装的内容）。
• 递归更新： gh-get update -r 查找位于或低于 当前目录，更新非重叠安装，并更新报告， 当前、跳过和失败的计数。
• 列表文件： gh-get -F gh-get.txt / gh-get update 同步a的每个条目 requirements.txt-样式列表；每个文件夹仍然有自己的 .gh-get-source。

认证

可选。代币提高了速率限制（60 → 5000 req/h）并启用私有 回购协议。解析顺序：--token 标志 → $GITHUB_TOKEN → $GH_TOKEN → gh auth token（如果安装并登录了GitHub CLI）。最后一步 意味着如果您已经运行了 gh auth login，gh-get 会获取该令牌 自动 - 不需要环境变量。

构建

go build -o gh-get .
# with version stamping:
go build -ldflags "-X main.version=v1.0.0" -o gh-get .

状态

v0.1.0：完整的 CLI，带有单元测试、自安装和 CI 交叉编译版本 所有六个 platform/arch 目标的工作流程发布二进制文件。延期：温盖特 （便携式）清单和 Homebrew Tap。完整设计请参见 CONTEXT.md 决定。