GitHub 基本操作

Git 负责本地版本历史，GitHub 负责托管、协作和界面，gh 负责在终端调用 GitHub。本文只建立这三者的使用边界，不重复讲 Git 对象、提交图或 rebase 的内部原理。

GitHub 不会替代 Git。一次日常协作通常同时经过三层：本地用 Git 创建提交，远程用 GitHub 保存并展示仓库，必要时用官方 GitHub CLI（gh）操作仓库、Issue、Pull Request（PR）和 Actions。Git 的远程同步细节见 Git 03：远程协同。

1. Git、GitHub 与 gh 的分工#

一个容易混淆的边界是：git push 是把 Git 提交发送到某个远程地址；它本身不知道 Issue 或 PR。gh pr create 才是在 GitHub 上创建 PR，且 PR 的目标是一个 GitHub 仓库中的基准分支。

另一个边界是：Git 能够在没有网络的情况下创建提交和分支；GitHub 的仓库、权限、Issue、PR 和 Actions 需要访问 GitHub 服务。gh 是调用 GitHub API 和网页相关能力的客户端，不是 Git 的替代品。

2. 认证与 gh auth#

2.1 选择 Git 传输协议

从本地向 GitHub 读写仓库时，常见协议有：HTTPS（如 https://github.com/OWNER/REPO.git，由凭据助手完成登录）和 SSH（如 git@github.com:OWNER/REPO.git，需登记公钥并可用 ssh -T git@github.com 检查）。两者都支持 clone、fetch 和 push；协议不决定仓库权限，权限由账户、可见性、协作者角色和分支规则共同决定。

2.2 用 gh 登录

先确认客户端存在，再启动交互式登录：

gh --version
gh auth login
gh auth status

gh auth login 会让你选择 GitHub 主机和 Git 协议，并通常打开浏览器完成授权。gh auth status 用于检查当前主机和账户状态；不要把它的完整输出或任何凭据粘贴到公开 Issue、日志或笔记中。

如果已经登录但 Git 操作仍无法写入，可以让 gh 为 Git 配置凭据助手：

gh auth setup-git

认证的安全边界：不要把 Personal Access Token（PAT）、SSH 私钥、GH_TOKEN、GITHUB_TOKEN 或内嵌凭据的远程 URL 写进仓库、脚本、shell 历史、.git/config 或日志。自动化 token 应放在 GitHub Secrets 或 Actions 提供的受限上下文中；不要运行或转发会直接输出令牌的命令。

认证只回答“你是谁、能否访问”；它不代表你可以向任意仓库 push。遇到 permission denied，先确认远程地址和登录账户，再检查仓库权限或改用 Fork 工作流。

官方说明：gh auth login、gh auth。

3. 创建、克隆与 Fork 仓库#

3.1 创建一个自己的仓库

网页路径会随 GitHub UI 调整；通常从右上角 + → New repository 进入，选择所有者、名称、可见性和初始化文件后创建。组织可能限制仓库创建，空仓库和带 README 的仓库在首次 clone/push 时也有不同提示。

也可以用 gh：

gh repo create my-project --private
gh repo create my-project --public --clone

--private、--public 是重要的可见性选择；不要为了测试公开含私密资料的仓库。--clone 会在创建成功后克隆到本地；从已有本地目录创建远程仓库可使用 --source 和 --push，但应先检查将要公开的提交和文件。

官方说明：创建新仓库、gh repo create。

3.2 Clone、Fork 与 Branch 不是一回事

因此，“Fork 一个仓库”不会自动把代码下载到电脑；“Clone 一个仓库”也不会自动创建你的 GitHub 仓库。贡献者常用组合是：先 Fork，再 Clone 自己的 Fork，最后在本地建立 feature branch。

3.3 Clone 到本地

Git 原生命令：

git clone https://github.com/OWNER/REPO.git
cd REPO

clone 会取得远程仓库当前可见的完整 Git 数据，而不仅是网页上显示的文件。浅克隆 git clone --depth 1 ... 可以节省时间和空间，但会缺少历史，后续比较旧提交、切换历史分支或生成某些版本信息时可能需要补齐历史。 clone 完成后可用 git status --short --branch、git remote -v 和 git branch --show-current 检查工作目录、远程地址和当前分支；这些命令不证明当前账户一定有写权限。

3.4 Fork 后的两个远程：origin 与 upstream

远程名称只是本地约定，不是 GitHub 的保留字：

• origin 通常指向你正在工作的远程仓库。Fork 工作流中，通常是你账户下的 Fork，可向它 push。
• upstream 通常指向原项目仓库，用于获取原作者的新提交。通常只能 fetch，是否能 push 取决于权限。

如果是从自己的 Fork clone，origin 可能已经指向 Fork；此时只需补上上游：

git remote add upstream https://github.com/OWNER/REPO.git
git remote -v

不要把 origin 或 upstream 当成“永远正确”的名字；真正重要的是用 git remote -v 确认每个名字对应的 URL。gh repo clone 对 Fork 可能自动添加 upstream，客户端版本和选项会影响这个行为，可用 git remote -v 验证。

官方说明：克隆仓库、gh repo clone、gh repo fork。

4. fetch、pull 与 push 的边界#

下面三条命令都涉及远程，但副作用不同：

4.1 先看，再整合

git fetch upstream
git log --oneline --decorate HEAD..upstream/main

HEAD..upstream/main 表示“远程有而当前分支没有”的提交；它是查看差异，不是合并。实际默认分支可能叫 master 或其他名称，先按仓库显示的默认分支替换 main。

如果当前分支没有未提交改动，并且希望把远程更新整合进本地分支，可以使用：

git pull --rebase origin main

pull --rebase 不是无冲突保证；它仍可能暂停要求解决冲突。对共享分支使用 rebase 前应遵守团队约定，因为 rebase 会重写本地提交的祖先关系。想分两步检查时，使用 git fetch，确认后再显式 git rebase 或 git merge。

4.2 首次推送与风险

确认当前分支、待推送提交和远程地址后，首次推送一个新分支：

git push --set-upstream origin feature/short-description

--set-upstream 会建立本地分支与远程跟踪分支的关系，之后可以直接使用 git pull 和 git push。git push 会把提交公开给拥有该远程访问权的人；它不会自动创建 PR。

不要把 git push --force 当作普通重试。它可能移动远程分支指针并使别人已经推送的提交暂时不可见。只有在确认是自己独占的分支、理解历史重写的影响并得到团队允许时，才考虑：

git push --force-with-lease origin feature/short-description

--force-with-lease 会在远程状态不符合本地预期时拒绝覆盖，比 --force 多一道保护；它仍然不是公共分支的常规操作。

5. 仓库网页、Issue、PR 与 Actions 导航#

GitHub 网页上的标签和按钮会变化，下面记录的是稳定语义。实际操作时以当前仓库显示的入口为准。

5.1 仓库首页与代码入口

• Code：获取 HTTPS/SSH clone 地址，查看文件和分支。
• Issues：记录 bug、任务、问题和功能想法；Issue 是讨论与跟踪对象，不是 Git 提交。
• Pull requests：比较一个 head 分支与 base 分支的差异，进行评审、检查和合并。
• Settings：管理可见性、协作者、分支规则、Secrets 等；需要相应权限。
• Actions：查看 workflow、运行记录、日志和失败步骤；仓库可能关闭 Actions 或限制可运行的 workflow。

终端中可用以下命令打开或查看入口：

gh repo view --web
gh issue list
gh pr list
gh run list
gh run view

5.2 Issue、Pull Request 与 Actions 的关系

一个常见的协作链是：

1. 在 Issue 中说明问题、预期行为、复现步骤或任务边界。
2. 在本地创建 branch，修改代码并提交。
3. 把 branch push 到自己有写权限的远程。
4. 创建 PR，将 head branch 指向目标仓库的 base branch。
5. GitHub Actions 对 push 或 PR 事件运行检查；维护者查看差异、评论和检查结果。
6. 通过评审与必需检查后，按仓库规则合并 PR。

Issue 与 PR 可以通过 Fixes #123 等关键词建立关联；合并时是否自动关闭 Issue 取决于目标仓库和引用方式。Actions 是事件驱动的自动化平台；本篇只需知道它会在 PR 或 push 等事件上产生检查，Workflow、Job、Runner、权限和缓存见 GitHub 专题后续笔记。

官方入口：Issues、Pull requests、理解 GitHub Actions。

6. 完整命令流：从 Fork 到 Push，再创建 PR#

下面假定：OWNER/REPO 是原仓库，YOUR_USER 是你的 GitHub 登录名，原仓库默认分支是 main。先在变量中替换占位符；这些变量不包含密码或 token。

6.1 创建 Fork 并准备远程

UPSTREAM_OWNER="OWNER"
REPO="REPO"
YOUR_USER="YOUR_USER"

gh auth status
gh repo fork "$UPSTREAM_OWNER/$REPO" --clone=false
git clone "https://github.com/$YOUR_USER/$REPO.git" "$REPO"
cd "$REPO"
git remote add upstream "https://github.com/$UPSTREAM_OWNER/$REPO.git"
git remote -v

如果 Fork 已经存在，跳过 gh repo fork，直接 clone 现有 Fork。若团队偏好 SSH，把两个 HTTPS URL 换成对应的 SSH URL；不要在 URL 中加入 token。

6.2 从上游默认分支建立开发分支

git fetch upstream
git switch -c fix/short-description upstream/main

如果原仓库默认分支不是 main，将命令中的 main 换成实际名称。git switch -c 创建并切换本地分支；它不会把分支发布到 GitHub。

6.3 检查、提交并推送

完成文件修改后，使用明确的路径进行检查和暂存：

git status --short
git diff --check
git diff
git add -- path/to/changed-file
git diff --cached --check
git commit -m "Fix the short problem description"
git push --set-upstream origin HEAD

git add -- path/to/changed-file 比无条件 git add . 更容易避免把 .env、构建产物、编辑器缓存或不相关文件放进提交。git push origin HEAD 推送当前所在分支，减少手写错分支名的机会；它仍然会发布该提交，执行前要确认 git remote -v。

6.4 创建 Pull Request

gh pr create \
  --base main \
  --head "$YOUR_USER:fix/short-description" \
  --fill

也可以在 GitHub 网页打开新推送的分支，选择 Compare & pull request。创建 PR 时确认：base 是原仓库及其目标分支，head 是你的 Fork 及其 feature branch；这两个方向选反会让 PR 进入错误的仓库或比较错误的分支。

创建后用以下命令查看：

gh pr status
gh pr checks
gh run list

等待 Actions 检查、回应评审意见并按仓库规则更新分支。修改后继续在同一 feature branch 提交并 push，已有 PR 会自动更新；不要为每个小修复重复创建 PR。

7. 常见误区与安全检查#

常见误区可以压缩成四条检查：

• Fork 不等于 Branch：Fork 是账户下的远程副本，Branch 是提交图上的开发线；前者解决“在哪里 push”，后者解决“如何隔离改动”。
• origin 不等于官方仓库：它只是本地默认远程名；Fork 工作流中通常指自己的 Fork，原项目另命名为 upstream。
• pull 不只是下载：fetch 只更新远程跟踪信息，pull 还会整合到当前分支并可能冲突；想先观察就先 fetch。
• Push 不会创建 PR：Push 更新远程 branch，PR 需网页操作或 gh pr create 显式创建；运行 CI 也不等于请求合并。

每次准备 fetch/push 前运行：

git remote -v

确认 URL 后再执行写操作。也不要硬编码所有仓库都有 main，或因为能 clone 就推断能 push；先确认默认分支、Fork 所有者、远程 URL 和账户，分支保护还可能要求 PR、评审或必需检查。

凭据和私密文件

如果发现 token、私钥、.env 或个人数据，先停止 push，移除并轮换已经暴露的凭据，再按仓库安全流程处理。删除文件的后续提交不等于历史中从未出现过；敏感信息一旦 push 就应视为已泄露。

官方资料#

• GitHub Docs：仓库创建与管理、克隆仓库
• GitHub Docs：Issues、Pull requests、理解 GitHub Actions
• GitHub CLI Manual、gh auth login、gh repo clone、gh repo fork
• Git 官方文档、git-clone、git-fetch、git-pull、git-push