本文详解 grgit 插件中 `push()` 方法的正确用法，重点解决“推送至特定远程分支（如 origin/master）失败”这一常见问题，通过 `refsorspecs` 参数实现精准分支控制，避免误推所有分支。
在 Gradle 项目中集成 Grgit（JGit 的 Groovy 封装）进行 Git 自动化操作时，许多开发者会尝试使用 grgit.push(remote: "master") 推送本地 master 分支到远程同名分支，却遭遇如下异常：
org.eclipse.jgit.errors.NoRemoteRepositoryException: master not found
该错误并非表示远程仓库不存在 master 分支，而是因为 remote: "master" 被 Grgit 解析为远程仓库别名（如 origin），而非分支路径——Grgit 将其误认为要连接名为 "master" 的远程仓库（类似 git push master ...），而该远程显然未配置，故报错。
✅ 正确做法是：显式指定引用映射（refspec），使用 refsOrSpecs 参数传入键值对，格式为 ["源引用": "目标引用"]。例如，将本地 refs/heads/master 推送至远程 refs/heads/master（即 origin/master）：
用大白话操作当前项目的 Git/GitHub——配置 GitHub（装 gh CLI + 登录 + 建仓库）、备份、拉取下载、查询历史、回滚代码、管理分支。当用户用日常语言表达 git 意图时触发（例如"git备份一下""git下载项目""git拉下来""git看看我改了啥""git回退到上一个版本""git新建个分支搞新功能""git合并到主分支""git
grgit.push(
refsOrSpecs: ["refs/heads/master": "refs/heads/master"],
tags: true
)
? 补充说明： "refs/heads/master" 是 Git 内部标准的分支引用格式； 若远程仓库别名为 origin（默认），上述 refspec 等价于执行命令： git push origin refs/heads/master:refs/heads/master如需强制推送（force push），可额外添加 force: true 参数。
⚠️ 注意事项：
- ❌ 避免使用 remote: "origin" + branch: "master" 组合——Grgit 当前版本（v4.x+）不支持 branch 参数与 remote 混用进行单分支推送；branch: "all" 是特例，但不具备选择性。
- ❌ remote: "refs/heads/master" 或 remote: "refs/remotes/origin/master" 均无效，因 remote 参数语义固定为远程仓库名，非 refspec。
- ✅ 若需推送多个指定分支（如 master 和 develop），可扩展 refsOrSpecs：
refsOrSpecs: [ "refs/heads/master": "refs/heads/master", "refs/heads/develop": "refs/heads/develop" ]
? 总结：Grgit 的 push() 方法中，refsOrSpecs 是实现精确分支推送的唯一可靠方式。它直接对应 Git 底层 refspec 机制，语义清晰、行为确定。务必摒弃对 remote 参数的误解，以引用路径（而非分支名或远程名）作为映射键值，即可安全、可控地完成 CI/CD 流水线中的定向发布任务。
