1 什么是 GitHub

GitHub 是全世界最大的面向开发者的代码托管平台，在分布式版本控制系统中扮演远程服务器的角色，帮助开发者们实现了代码和文档的高效协同开发，包括但不限于贡献代码（Pull Request），报告问题（Issues）和进一步的讨论（Discussions）。

中文官方文档

多人开发视频教程（bilibili）

2 多人协同开发

以下我们以 GitHub 为例，通过介绍 GitHub 项目主页上的每个条目，引入多人协同开发流程。这里我们希望你可以配合 Git 的基本操作流程来在本地通过命令行更方便高效的进行项目管理。

在 GitHub 上创建仓库

在个人主页 -> Repositories 内点击，填写仓库的信息，点击即可创建一个新的仓库。随后跟随 GitHub 的提示，将本地仓库推送到远程仓库。

在 GitHub 上开发

从 GitHub 克隆代码

与其他开发者合作的第一步就是从远程仓库中获取项目的本地拷贝（项目的源码、历史记录、分支、标签都在里面），即克隆（clone）代码到本地。

以 Open-EM 项目为例，为了在本地可以方便的修改和编辑，首先在项目主页的中 Clone 命令下的 HTTPS 选项中点击复制仓库的 URL
```
 https://github.com/Cellverse/Open-EM.git
```
。对于配置了 SSH key 的用户（如何新增SSH密钥到Github账户），可以使用
```
 git@github.com:Cellverse/Open-EM.git
```
这样在后续提交修改的代码时可以免于重复输入用户名和密码。
在本地打开终端，git clone <URL>: 克隆远程项目。
- git clone <URL> <name>: 可以指定本地文件夹的名字。
- 此时用 git branch 只能看到 main 分支，但是可以切换到 GitHub 上存在的分支。

从 GitHub 拉取代码

在进行本地开发的时候，其他的开发者可能向远程仓库提交了新的代码或进行了修改，因此我们需要从远程仓库中更新代码，即拉取代码（pull）到本地：

在对应的本地仓库的路径下打开终端，git branch: 确保在正确的分支下拉取代码。
git pull origin <branch>: 从远程仓库的指定分支拉取文件到文件夹。这条命令等同于下面两条命令
- git fetch origin <branch>: 从远程仓库的指定分支拉取文件到版本库。
- git merge origin/<branch>: 从版本库合并到本地文件夹。
此时如果本地代码与远程代码有冲突，Git 会拒绝执行合并操作。此时你需要解决代码冲突。打开文本编辑器，搜索冲突标记 <<<<<<<、=======、>>>>>>>，你将会看到类似于这样的文本：
```
 <<<<<<< HEAD
 远程仓库的文本
 =======
 你的文本
 >>>>>>> <YOUR_BRANCH>
```
选择你想要保留的文本，删除冲突标记，保存文件。
提交并推送一个解决了版本冲突的本地最新版本。

:bulb: 远程仓库名字 origin 与分支名字 main 一样，没有任何特别的含义，仅仅是因为约定俗成。main 是运行 git init 时默认的起始分支名字；origin 是运行 git clone 时默认的远程仓库名字。

推送代码到 GitHub

当本地开发完成时，你就可以将代码推送（push）到远程仓库：

在本地生成一个新的版本：
- git add <file>: 将文件添加到版本库，<file>是文件名，你也可以在项目的根目录下通过 git add . 添加所有有改动的文件。
- git commit -m <message>: 将文件提交到版本库，<message>是你希望备注给自己和其他开发者的修改简介，字数不宜太多。
- git rebase -i HEAD~<n>: （可选）将最近的 n 个版本合并为一个版本，让版本信息更加清晰。
从远程仓库拉取代码，一个分支可能由多个人同时开发，确保本地代码是最新的。
git push origin <branch>: 将本地版本推送到远程仓库的指定分支。

GitHub Issues

这里我们简单介绍一下Issues，它是 GitHub 开源项目中提出需求和 bug 的地方。

提出问题

在提出任何问题之前，如果已经有了不少被回答的问题，你可以先搜索是否有人已经提出了类似的问题来节约自己的时间，如果没有，你需要新建一个 issue。
点击，填写问题描述，点击提交问题，等待其他人回答。

GitHub Pull Requests

当你不是某个开源项目的团队成员时，你必须先 Fork 开源仓库进行开发。Fork 的含义是分叉。具体来说：

在 GitHub 网页的右上角有一个 Fork 按钮，点击后原本仓库的一切历史信息会复制并创建一个新的仓库到自己的 GitHub 账户中。Fork 对原本的仓库没有影响。
在自己远端仓库开发完毕后，就可以创建 Pull Request 到原本的仓库。

当你是某个开源项目的团队成员，你可以用更为直接的方法。

Clone 远程仓库到本地。
git checkout -b <branch>: 在本地建立一个新的分支，<branch> 是你希望创建的分支名字，一般与你要开发的功能相关。
- 未经审核向 main 分支提交代码会扰乱开发流程，因此你需要在本地创建一个新的分支进行开发。
- 如果你想要在本地创建一个已经存在的远程分支，可以使用 git checkout <branch>。
在本地进行开发，你可以执行多次推送代码到 GitHub。
- git push --set-upstream origin <branch>: 当你要将代码传到远程仓库的新分支时，你需要告诉远程仓库你创建了一个新的分支。
- 后续的提交仅需 git push origin <branch>。
git checkout main: 在新的 branch 上开发完毕后，切换回到 main 分支。
git pull origin main: 拉取最新的代码。
git checkout <branch>: 切换回到你的分支。
git rebase main: 同步 main 分支的代码到你的分支，可能需要处理冲突。
git push -f origin <branch>: 推送最终版本到远程仓库，随后你就可以在 GitHub 网页上创建 Pull Request 了。
- 由于 rebase 会改变提交的历史，因此你需要使用 -f 参数强制推送。

Pull Request

在原本的仓库页面的上方中点击 Pull requests，点击，可以比较两个分支。左侧的仓库 + 分支是目标分支，右侧的仓库 + 分支是来源分支。
当选定了目标分支和来源分支，并且两个分支之间没有冲突，点击创建 Pull Request。
添加这次 Pull Request 的标题和描述，再点击，正式创建新的 Pull Request。由项目管理者进行代码审查和。

代码审查

当 Pull Request 提交后，团队管理者此时可以直接接受，要求一些符合项目规范的修改或建议（绝大多数情况），或者拒绝 Pull Request。一般情况下，经过几轮修改，优质的 Pull Request 就会被开发者接受。

当项目中所要开发的特性都已经完成可以生成一个发布版本时候，就需要 git tag。

git tag -a <tag> -m "message" 打上标签做版本。

git push --tag 提交打上标签的版本到远端。

GitHub Discussions

Discussions 类似于 Issues，但是更加适合进行一般的讨论。除此之外，Discussions 的作用还有

共享公告和信息、收集反馈、计划和决策。
提出问题、讨论和回答问题，以及将讨论标记为已回答。
创建投票以衡量社区意见。

发起讨论

点击，再点击选择讨论分类，填写讨论标题和内容，点击发起讨论。

GitHub Wiki

Wiki 是项目介绍文档。由项目管理者、团队成员和贡献者共同维护。目前 Open-EM 单独有官网主页，故不详细介绍此功能gi。

4 杂项

邀请成员

GitHub 的 settings -> collaborators 邀请，适合个人，单个项目。

GitHub 的 organizations 邀请，适合团队，多个项目。

GitHub 免密登陆

Git 自动管理凭证

一般 Windows 和 MAC 自带，在你第一次输入账号和密码后，后续提交就无需密码。

在配置文件中修改 url

  origin: url = https://gitHub.com/xxx/xxx.git
  change: url = https://username:password@github.com/xxx/xxx.git

SSH
1. $ ssh-kengen 生成公钥和私钥，默认存放在 ~/.ssh/ 中，id_rsa.pub 为公钥，id_rsa 为私钥。
2. 拷贝公钥到 GitHub 的 SSH and GPR keys 中。
3. 在本地文件中配置 ssh 地址
```
 git remote add origin git@github.com/<user_name>/<repository>.git
```

基础知识

数据处理案例

GitHub 教程