SuperAPI AI 工具集

gion

编程与开发

查看项目

更新于 10-21 16:54

技能介绍

用途

gion 用于在不克隆整个仓库的前提下操作远程 Git 仓库。它按需从远程读取文件、目录树和提交,并可直接把提交推送到远程,磁盘上不保留完整历史。工作区只包含一个精简的本地 .git,使基于 git 的工具仍能工作。官方建议:对于尚未检出的仓库,优先使用 gion 而非 git clone;如果仓库已在本地检出且为最新,则直接使用该检出和 git。

主要能力

  • 读取与搜索(无需工作区):
    • gion ls owner/repo HEAD:src --md:列出目录
    • gion cat owner/repo HEAD:src/app.go:读取原始文件字节
    • gion find owner/repo 'handler' --md:按子串或 glob 搜索整个仓库的路径
    • gion grep owner/repo 'func New\w+(' --md:搜索整个仓库的内容
    • gion grep owner/repo 'TODO' --path src --md:限定路径搜索
    • gion diff owner/repo main~1 main --md:查看提交之间的变更
    • gion diff owner/repo HEAD --stat:查看最后一次提交的变更(--name-status 或完整 diff)
    • gion log owner/repo main -n 20 --md:查看最近提交
    • gion log owner/repo --path src/api --md:查看改动某路径的提交
    • gion blame owner/repo HEAD:src/app.go -L 40,60 --md:查看指定行的最后修改者
    • gion ls-refs owner/repo:列出分支和标签
  • 编辑与推送:
    • 少量文件、无工作区:本地写好新内容后执行 gion commit owner/repo -m "msg" --branch my-fix src/a.go=./a.go --rm src/old.go --md。--branch b 从 HEAD 创建分支(--onto <rev> 指定其他基点),--to b 更新已有分支。
    • 真实编码场景:使用稀疏工作区,只克隆任务涉及的目录。父目录(含根目录)中的文件会一并带出,因此 .gitignore、pyproject.toml、package.json、go.mod、conftest.py 和 lint 配置都在;对它们的编辑会被提交,但紧邻它们的新文件除非用 gion add 添加,否则不会被提交。
    • 工作区命令:gion clone owner/repo ./ws --path src/api --path go.mod --md;gion status --md;gion diff --md(gion diff <path> 查看单个文件或目录);gion add src/shared --md 扩展工作区;gion commit -m "msg" --branch my-fix --md(首次推送创建分支);gion commit -m "more" --md(后续推送更新分支);gion sync --md 将上游变更拉入未编辑文件;gion switch other-branch --md 切换到已有分支并保留编辑;gion log --md 查看已检出内容的历史,gion blame <file> --md;gion rebase --md 将分支重放到默认分支并推送。
  • pre-commit 与基于 git 的检查:工作区有本地 .git 快照并由 gion 保持同步,因此 git diff、git status 和 pre-commit 可用。若仓库有 .pre-commit-config.yaml,运行一次 pre-commit install;之后 gion commit 会在推送前对所有变更运行钩子,失败则不推送(格式化工具会把修复留在磁盘上,再次提交即可)。pre-commit run --all-files 检查全部内容。推送请用 gion commit,不要用 git commit / git push。
  • rebase 冲突处理:gion rebase 遇到冲突会停止并列出文件。每个文件带有标记:<<<<<<< <new base>(上游版本)、||||||| base(任一变更之前)、=======、>>>>>>> <commit>(你的变更)。将文件编辑为最终内容,在不矛盾处保留双方意图(或删除文件以接受删除),用 gion diff --md 检查,然后 gion rebase --continue --md。--skip 丢弃该提交;--abort 恢复一切。完成前不会推送,且推送是 compare-and-swap。无工作区时,若无冲突,gion rebase owner/repo my-branch --md 也可用。
  • 推送语义:推送为 compare-and-swap。若他人向该分支推送了其他文件,gion 会在其之上构建并把他们的文件写入磁盘;若他们改动了你的文件,则停止并列出这些文件。新分支的 --md 输出包含打开 PR 的链接。

使用方式

安装:go install github.com/baz-scm/gion@latest(二进制位于 $(go env GOPATH)/bin),然后 gion skill install 保持技能与二进制同步。

认证(仅私有仓库和推送需要):gh auth login,或设置 GITHUB_TOKEN,或使用 git 凭据助手。gion 不存储凭据。

<remote> 为 owner/repo(GitHub)或任意 git URL。<rev> 为分支、标签、HEAD、提交 id(GitHub 上短 id 可用),可带可选 ~N/^N(如 main~2)。

建议起点:用 ls/find 定位,用 grep 查找,用 cat 读取。即使仓库很大也只需数秒。

适用场景

  • 需要快速读取、搜索或对比远程仓库而不想完整克隆时。
  • 需要直接向远程分支推送少量文件改动时。
  • 需要稀疏检出、只处理任务相关目录并运行 pre-commit 检查时。
  • 需要以面向智能体的 Markdown 输出进行仓库操作时。

限制与规则

  • 不要为了读取或搜索而执行不带 --path 的 git clone 或 gion clone:应使用 cat、find、grep。
  • 在稀疏工作区内,文件工具只能看到已克隆路径。搜索仓库其余部分用 gion grep <remote> / gion find <remote>,需要编辑的内容用 gion add 添加。
  • 除非被要求,否则推送到分支而非默认分支。
  • 在工作区运行测试时,用 gion add 添加测试目录及其导入的代码。若这几乎是整个仓库,则推送分支让 CI 运行。
  • 推送无法通过 force-push 撤销:每次提交前用 gion status --md 检查,避免忽略或生成的文件混入。
  • gion 没有 merge:用 gion rebase 使分支保持最新。若冲突的正确解决方式无法从代码中明确判断,应询问用户而非猜测。
  • 运行 gion help 查看所有标志。