GitHub 仓库管理工具 gh 常用命令总览

平时我们在命令行里管理 GitHub 仓库时，如果只靠网页操作，很多流程都会显得有点碎。比如查看 PR、创建 Issue、切分支、拉取远程仓库信息、检查登录状态，这些动作来回切页面确实容易把人搞烦。

这时候 gh 就很顺手了。它是 GitHub 官方提供的命令行工具，可以直接在终端里完成仓库、Issue、PR、Release、Actions 等常见操作。对于经常在服务器、WSL 或者终端开发环境里工作的同学来说，真的属于“装了就回不去”的那类工具。

这篇文章把我平时高频使用的 gh 命令做一个整理，方便自己回头查，也方便读者快速上手。

一、gh 是什么

gh 是 GitHub CLI，也就是 GitHub 官方维护的命令行工具。

它适合做的事情包括：

  • 在终端中登录 GitHub 账号
  • 克隆、查看和管理仓库
  • 创建、查看和合并 Pull Request
  • 创建、查看和关闭 Issue
  • 查看 GitHub Actions 工作流执行情况
  • 管理 Release、Gist 等资源

如果你的工作流本身就偏命令行，那 gh 基本可以把不少网页操作搬回终端。

二、安装与登录

1. 安装 gh

跨平台安装（推荐）

如果你已经安装了 x-cmd，可以直接用它做跨平台安装，比较方便：

x install gh

不同平台下的安装

Windows（winget）

winget install --id GitHub.cli

Ubuntu / Debian

sudo apt install gh

macOS（Homebrew）

brew install gh

安装完成后先检查版本：

gh --version

2. 登录 GitHub

首次使用通常先执行：

gh auth login

然后按照提示选择：

  • GitHub.com 或企业版实例
  • HTTPS 或 SSH
  • 浏览器授权或 Token 授权

查看当前登录状态：

gh auth status

退出登录：

gh auth logout

三、gh 和 git 如何配合使用

很多人第一次接触 gh 时，都会有一个很自然的问题：

既然已经有了 gh，那它是不是可以直接替代 git pull、git push、git commit 这些命令？

答案是：不能完全替代。

更准确地说，git 和 gh 最适合的关系是“分工协作”：

  • git 负责本地版本控制和代码同步
  • gh 负责和 GitHub 平台交互

你可以简单理解成：

  • git 管代码历史
  • gh 管 GitHub 事务

例如下面这些动作，更适合交给 git：

  • git add
  • git commit
  • git pull
  • git push
  • git reset
  • git revert

而下面这些动作，更适合交给 gh：

  • gh auth login
  • gh repo clone
  • gh repo view
  • gh issue list
  • gh pr create
  • gh pr view
  • gh run list

所以在日常开发中，最常见的方式并不是“只用 gh”或者“只用 git”，而是两者配合使用。

1. 服务器里首次开发前，先配置 Git 身份

如果你是在服务器、WSL、新电脑或者新开的开发环境里第一次提交代码，建议先检查 Git 身份信息。

查看当前配置：

git config --global user.name
git config --global user.email

如果没有配置，就补上：

git config --global user.name "your_name"
git config --global user.email "your_email@example.com"

你也可以直接查看所有全局配置：

git config --global --list

这里有两个实际开发中很容易踩坑的点：

  • 没有配置 user.name 和 user.email 时，提交可能直接报错
  • 邮箱如果和 GitHub 账号不匹配，贡献记录可能不会正确关联到你的账号

如果你不想暴露真实邮箱，也可以在 GitHub 设置页里使用官方提供的 noreply 邮箱。

2. 认证成功后，确认你使用的是哪种连接方式

执行下面命令登录 GitHub：

gh auth login

登录过程中通常会让你选择：

  • HTTPS
  • SSH

这两种方式都能用，但建议你在同一台机器上尽量保持一致，不然有时候会出现“登录成功了，但推送方式和远程地址不匹配”的尴尬情况。

克隆或进入仓库后，可以用下面命令检查远程地址：

git remote -v

如果你看到的是：

  • https://github.com/...，说明当前仓库走的是 HTTPS
  • git@github.com:...，说明当前仓库走的是 SSH

3. 一套最常见的 git + gh 配合工作流

下面这套流程，基本就是我自己比较推荐的终端开发方式，尤其适合服务器和远程环境：

# 1. 配置 Git 身份
git config --global user.name "your_name"
git config --global user.email "your_email@example.com"

# 2. 登录 GitHub
gh auth login

# 3. 克隆仓库
gh repo clone owner/repo

# 4. 进入项目目录
cd repo

# 5. 新建功能分支
git checkout -b feature/demo

# 6. 正常开发后提交
git add .
git commit -m "feat: add demo"

# 7. 推送到远程
git push -u origin feature/demo

# 8. 创建 Pull Request
gh pr create

# 9. 在浏览器中查看 PR
gh pr view --web

这套流程里分工其实很清楚：

  • gh 负责登录、克隆、提 PR、看 PR
  • git 负责分支、提交、拉取、推送、回退

4. 那 gh 里有没有类似 git pull 和 git push 的命令？

这是最常被问到的问题之一。

严格来说，日常开发中的 pull 和 push，还是应该优先使用 git pull 和 git push。

也就是说：

git pull
git push

这两个动作仍然是 Git 自己的职责范围。

gh 并没有一个在日常开发里完全等价替代 git push 的核心命令。它更偏向：

  • 帮你登录 GitHub
  • 帮你 clone / fork 仓库
  • 帮你创建和查看 PR
  • 帮你查看 Actions 和 Issue

有些同学会看到 gh repo sync，但这里要特别说明：

gh repo sync owner/repo

它更偏向 同步 fork 仓库和上游仓库，并不是普通开发工作流里 git pull 的直接替代。
所以如果你只是想把远程最新代码拉到本地，老老实实用 git pull 就对了；如果你是想把本地分支推上去，也还是 git push 更直接。

5. 版本回退和撤销修改，一般还是用 git

虽然本文主题是 gh，但只要讲工作流，就绕不开版本回退。

这里我把最常见的几个场景一起整理一下。

场景 1：文件改乱了，但还没提交

git restore <file>

如果想恢复当前目录下所有未提交修改：

git restore .

场景 2：已经 git add 了，但不想暂存

git restore --staged <file>

如果要把所有暂存都撤掉：

git restore --staged .

场景 3：已经提交了，但想回到上一个版本

保留工作区修改，只撤销提交：

git reset --soft HEAD~1

连工作区一起强制回退：

git reset --hard HEAD~1

这个命令威力很大，如果你不确定，就别轻易对重要分支执行 --hard。

场景 4：已经推送到远程了，但想安全撤销某次提交

这时候更推荐用：

git revert <commit_id>

它不会粗暴改写历史，而是新建一个“反向提交”来撤销之前的修改。
如果这个分支已经被别人拉取、或者已经进入协作流程，通常优先选择 revert，会更稳。

四、仓库相关常用命令

1. 克隆仓库

gh repo clone owner/repo

例如：

gh repo clone cli/cli

如果想克隆到指定目录：

gh repo clone owner/repo my-local-dir

2. 查看仓库信息

gh repo view owner/repo

查看当前目录关联仓库的信息：

gh repo view

如果想直接在浏览器打开仓库：

gh repo view --web

3. 创建新仓库

gh repo create

也可以一步到位指定名称：

gh repo create my-demo --public

常见参数：

  • --public：创建公开仓库
  • --private：创建私有仓库
  • --clone：创建后直接克隆到本地
  • --source .：把当前目录作为仓库内容推送上去

4. Fork 仓库

gh repo fork owner/repo

如果希望 fork 后顺手 clone 到本地：

gh repo fork owner/repo --clone

5. 在浏览器中打开当前仓库

gh repo view --web

这个命令很适合“终端里改完，网页里看一眼”这种场景。

五、Issue 相关命令

1. 查看 Issue 列表

gh issue list

查看指定仓库的 Issue：

gh issue list --repo owner/repo

常见筛选：

gh issue list --state open
gh issue list --assignee @me
gh issue list --label bug

2. 查看某个 Issue

gh issue view 123

在浏览器中打开：

gh issue view 123 --web

3. 创建 Issue

gh issue create

直接在命令行中指定标题和内容：

gh issue create --title "fix: 修复登录页按钮样式" --body "按钮 hover 状态异常，需要统一样式。"

4. 关闭 Issue

gh issue close 123

如果要顺便留下关闭说明：

gh issue close 123 --comment "已在最新提交中修复。"

六、Pull Request 相关命令

1. 查看 PR 列表

gh pr list

常见筛选方式：

gh pr list --state open
gh pr list --author @me
gh pr list --assignee @me

2. 查看某个 PR

gh pr view 25

在浏览器打开：

gh pr view 25 --web

查看 PR diff：

gh pr diff 25

3. 创建 Pull Request

先确保你已经把本地分支推送到远程，然后执行：

gh pr create

也可以直接带参数：

gh pr create --title "feat: 新增文章搜索页" --body "补充搜索入口，并优化移动端布局。"

如果想指定 base 分支：

gh pr create --base main --head feature/search-page

4. 检出某个 PR 到本地

gh pr checkout 25

这个命令在帮别人 review 代码时特别方便，不需要自己手动找远程分支名。

5. 合并 PR

gh pr merge 25

常见合并方式：

gh pr merge 25 --merge
gh pr merge 25 --squash
gh pr merge 25 --rebase

6. 关闭 PR

gh pr close 25

七、工作流与 Actions 相关命令

1. 查看 workflow 运行记录

gh run list

2. 查看某次运行详情

gh run view RUN_ID

3. 查看日志

gh run view RUN_ID --log

4. 重新运行失败任务

gh run rerun RUN_ID

5. 在浏览器打开 Actions 页面

gh run list --web

如果你在维护博客自动部署、CI 检查或者测试流水线，这一组命令查问题很省时间。

八、Release 与其他实用命令

1. 查看 Release 列表

gh release list

2. 创建 Release

gh release create v1.0.0

带说明一起创建：

gh release create v1.0.0 --title "v1.0.0" --notes "首个正式版本发布。"

3. 下载 Release 附件

gh release download v1.0.0

4. 查看当前账号信息

gh api user

5. 打开当前目录对应网页

gh browse

这个命令非常偷懒，但很好用。

九、我自己最常用的一组组合命令

如果你只是想先记住最常用的那几个，可以先从下面这些开始：

# 登录与检查
gh auth login
gh auth status

# 仓库
gh repo clone owner/repo
gh repo view --web

# Issue
gh issue list
gh issue create

# Pull Request
gh pr list
gh pr create
gh pr view 12 --web
gh pr checkout 12
gh pr merge 12 --squash

# Actions
gh run list
gh run view RUN_ID --log

十、使用建议

如果你是第一次在服务器里使用 GitHub 开发环境，我建议把下面这几个动作固定下来：

  • 先检查 git config --global user.name 和 git config --global user.email
  • 再执行 gh auth login
  • 克隆仓库后先看一眼 git remote -v
  • 日常同步代码用 git pull
  • 提交本地分支用 git push
  • Pull Request、Issue、Actions 这些 GitHub 事务再交给 gh

这样分工最清楚，也最不容易混乱。

gh 很强，但我建议别一开始就把所有子命令都背下来。先记住你当前工作流里最常用的 5 到 8 个命令就够了，比如：

  • gh auth login
  • gh repo view --web
  • gh issue list
  • gh pr list
  • gh pr create
  • gh pr checkout
  • gh run list

等你开始习惯在终端里处理 GitHub 事务之后，再慢慢补充其他命令，会比一次性硬记舒服得多。

十一、总结

gh 本质上就是把 GitHub 上那些高频但重复的网页操作，压缩成了一条条终端命令。对于经常写代码、提 PR、看 CI、管仓库的人来说，它能明显减少上下文切换的成本。

不过也要记住一点：**gh 很好用，但它不是 git 的替代品。** 更准确的用法，是让 git 负责代码历史和同步，让 gh 负责 GitHub 平台上的协作流程。两者搭配起来，体验才是完整的。

如果你平时已经离不开 git，那我建议顺手把 gh 也装上。很多时候你会发现，原来一个浏览器里点半天的流程，在终端里一句命令就结束了，确实挺香。

参考资料