前言

在上一篇文章中，我们详细了解了 Git 的基本概念、工作流和常用命令。在本文中，我们将通过一个实际的项目案例，来逐步演示如何在 GitHub 上进行代码托管和协作。

本次演示仓库以我和国科大的好哥们共同开发的c语言围棋游戏为演示仓库 AstreoX/CGo，其中的 ai.c 演示了一个基于蒙特卡洛树搜索（MCTS）的决策示例。本文将引导你从 安装配置、命令行操作 到 VS Code 可视化，一步步学会如何：

  1. Fork & Clone
  2. 创建分支 & 修改参数
  3. 本地 Commit & Push
  4. 发起 Pull Request
  5. 参与代码审阅与合并

安装与初始配置

1. 安装 Git

  • Windows、macOS、Linux 均可从官网下载安装包：

    text
    https://git-scm.com/download/

上一篇文章已有详细说明，这里不再赘述。

  • 安装完成后，在终端（Windows PowerShell / macOS Terminal / Linux Shell）输入：

    bash
    git --version

    应看到类似 git version 2.x.x 的输出。

2. 全局配置

bash
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

这两个信息会出现在每次提交记录中。

3. 注册 GitHub 账号

  1. 打开 https://github.com 并注册。

  2. 完成邮箱验证。

  3. （强烈建议）在 Settings → SSH and GPG keys 添加你的 SSH 公钥，以便后续无需每次输入密码：

    • 首先我们在空白处右键，在右键菜单的更多选项中选择”Open Git Bash Here”
    截图：右键菜单中的 Open Git Bash here 选项被红框标出
    截图：刚打开的 Git Bash 终端窗口，路径为 /d

    • 然后输入以下命令（邮箱记得替换成你自己的，注意不要有空格，然后一路无脑回车即可）：

      bash
      ssh-keygen -t ed25519 -C "you@example.com"

    • 然后将生成的私钥添加到ssh-agent中：

      bash
      eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

    • 接着Git Bash中输入下面命令：

      bash
      cat ~/.ssh/id_ed25519.pub

    • 然后将显示的公钥内容复制到剪贴板

    • 然后打开GitHub，在右上角的头像菜单中选择”Settings”

    截图：GitHub 主页，红箭头指向右上角的头像
    截图：头像菜单展开，红框标出 Settings 选项
    • 然后在左侧菜单中选择 “SSH and GPG keys”
    截图：设置页左侧菜单，红框标出 SSH and GPG keys
    • 然后点击”New SSH key”
    截图：SSH keys 页面，红框标出右上角 New SSH key 按钮
    • Title 随便取一个，将刚刚复制的公钥内容粘贴到 Key 中，然后点击”Add SSH key”
    截图：Add new SSH Key 表单，有 Title 与 Key 输入框

    • 至此，我们的SSH公钥就添加成功了

    • 最后，我们可以测试一下是否成功：

      bash
      ssh -T git@github.com

      然后输入”yes”，如果显示”Hi username! You’ve successfully authenticated, but GitHub does not provide shell access.”，则说明成功了

Fork & Clone 仓库

无论命令行还是 VS Code，可视化，第一步都是 Fork 一份到自己账号并拉到本地。

  1. 访问我的仓库：

    text
    https://github.com/AstreoX/CGo

  2. 点击右上角 Fork，将仓库复制到 yourname/CGo。

    截图：AstreoX/CGo 仓库页，红框标出右上角 Fork 按钮

  3. 再进入到你Fork的仓库，点击 Code，复制仓库地址。

    截图：点开 Code 下拉菜单，复制 SSH 克隆地址

  4. 在你本地的电脑上，创建一个合适的文件夹来作为项目目录（建议路径要为全英文），然后老样子右键点击空白处，选择”Open Git Bash Here”

    截图：右键菜单中的 Open Git Bash here 选项被红框标出

  5. 接着输入git clone空格之后，将你刚刚复制的仓库地址粘贴进去，然后回车即可

    截图：Git Bash 中输入 git clone 并粘贴仓库地址

  6. 此时，Git就会开始在本地克隆远程仓库的内容到你指定的目录中。

    截图：Git Bash 显示 git clone 克隆 CGo 的进度输出

  7. 然后，你就可以在本地看到克隆的仓库代码了。

    截图：资源管理器中克隆下来的仓库文件列表

传统命令行工作流

初始化仓库 & 添加上游

Git Bash窗口不要关掉，接着输入以下命令：

bash
cd CGo
# 添加上游指向原仓库（便于后续同步主分支）
git remote add upstream https://github.com/AstreoX/CGo.git
git remote -v
# 应看到 origin（你的仓库）和 upstream（原仓库）
截图：Git Bash 添加 upstream 并查看远程仓库

分支管理

  1. 查看当前分支：

    bash
    git branch

  2. 创建并切换分支：

    bash
    git checkout -b tune-mcts
截图：Git Bash 查看分支并新建切换到 tune-mcts 分支

修改 & 提交

  1. 用你喜欢的编辑器打开 src/ai.c，在程序的第19-23行找到：

    截图：ai.c 第 19 至 23 行的 MCTS 参数宏定义

    根据注释调整MCTS的搜索参数，做出一些修改

  2. 保存后回到命令行：

    使用以下命令查看文件状态：

    bash
    git status
    截图：git status 显示 src/ai.c 已被修改

    会看到src/ai.c被标记为修改

    然后使用以下命令将修改添加到暂存区：

    bash
    git add src/ai.c
git diff --staged   # 查看暂存区对比，能看到你改动了代码的哪些地方
git commit -m "在这里记录你修改的参数，例如：Tune MCTS: sim=2000, exploration=1.20"
    截图：git diff --staged 的改动对比与 git commit 结果

推送 & 发起 Pull Request

bash
# 推送到你远程仓库
git push -u origin tune-mcts
截图：git push -u origin tune-mcts 的推送输出
  • 之后访问 https://github.com/yourname/CGo
  • 页面会提示 “Compare & pull request”，说明你已经成功推送了分支，需要发起 Pull Request。
截图：仓库页顶部提示推送，红框标出 Compare & pull request
  • 点击 “Create pull request”，填写标题和描述，然后点击 “Create pull request”。
截图：Open a pull request 页面，填好描述后点 Create pull request
  • 然后就会跳转到Pull Request页面，你可以在这里查看你的改动、发起评论、参与讨论等。
  • 这里显示没有代码冲突，直接点击 “Merge pull request” 即可。
截图：PR 页面提示无冲突，红框标出 Merge pull request
  • 然后点击 “Confirm merge” 即可完成合并。
截图：合并提交信息表单，红箭头指向 Confirm merge 按钮
  • 然后就可以看到你的改动已经被合并到主分支了。

VS Code 可视化工作流

在刚刚克隆到本地的代码仓库，右键选择”Open with Code”，或者直接在VS Code中打开该文件夹，就可以开始可视化操作了。

安装必备扩展

  1. GitLens — Git supercharged：增强代码注释与历史浏览。
  2. GitHub Pull Requests and Issues：在 VS Code 中直接浏览/发起 PR。

分支与改动管理

  • 切换/创建分支：

    • 点击下方加号 → “Create new branch” → 输入 tune-mcts-2 → 按回车创建
    截图：合并提交信息表单，红箭头指向 Confirm merge 按钮
    截图：VS Code 的 GitLens 提交图，红框标出新建分支按钮

    这里会出现三个选项，我们只需要关心前两个，分别是单纯的创建分支、创建分支并切换到该分支。
    根据自己的喜好选择即可（一般情况下，我们选择创建分支并切换到该分支）

  • 查看改动：

    • 在 源代码管理 面板能看到所有未暂存与已暂存的文件
    • 点击文件名可打开 diff 视图

修改 & 提交

  1. 在资源管理器中打开 src/ai.c，修改参数并保存。

  2. 在 源代码管理 面板：

    • 将 ai.c 拖动到 “Staged Changes”

    • 在上方输入提交信息：

      Tune MCTS: sim=2000, exploration=1.20

    • 点击 ✓ 提交

推送 & 发起 PR

  • 推送：顶部会出现 “Publish Branch” 按钮，点击即可。

  • 发起 PR：

    • 安装 “GitHub Pull Requests and Issues” 后，点击左侧 “GitHub” 图标
    • 选择 “Create Pull Request” → 目标库选择 AstreoX/CGo → 填写标题和描述 → 提交

总结

通过以上 命令行 + VS Code 可视化 的方式进行版本控制，我们可以更方便地管理代码，并与他人协作。在实际开发中，我们可以根据需要灵活选择适合自己的版本控制方式，以提高开发效率。

无论是通过命令行还是可视化工具，Git 和 GitHub 的核心概念和工作流程都是一致的：

  • Fork 仓库到自己账号
  • Clone 到本地进行开发
  • 创建功能分支进行修改
  • 提交并推送更改
  • 发起 Pull Request 进行代码审阅
  • 合并到主分支

掌握了这些基本操作，你就可以参与到开源项目的协作中，或者在团队开发中高效地进行版本控制了。