HaveFunWithEmbeddedSystem/Chapter3_项目管理与团队协作/3.8_协作工具.md

# 3.8 协作工具

无论是团队协同开发还是独自开发，都难免要使用一些软件管理工具。在软件开发过程中，除了常用的 IDE 外，还经常用到差分工具、版本管理工具、代码托管和协作工具。这其中比较有代表性的开源工具是：Meld、Git 和 Gitea。

## 3.8.1 Git 版本管理

Git 版本管理工具提供本地和远程版本管理功能。支持分支管理和 Tag 创建等。通常来讲，一个 Tag 对应一个稳定的软件版本。

使用 Git 前需要进行简单配置，在命令行中输入以下命令及参数设置 Git 用户名和 Email。

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

### 3.8.1.1 创建仓库

软件版本管理依赖于软件仓库的概念，一个软件仓库包容了要进行版本管理的源码和 Release 发布等内容。

在要进行版本管理的目录下键入：

    git init

命令，可完成软件版本仓库的创建操作，在创建完软件仓库后，该目录下会生成一个名为“.git”的隐藏文件夹，该文件夹下保存了软件的历史和分支等版本信息，通常不需要直接操作该目录。

### 3.8.1.2 添加管理文件

版本仓库所在文件夹下的文件并不是全部都会被 git 跟踪和管理。如果需要将该文件夹下将某个文件纳入到版本管理中，则需要通过 add 命令添加到 git 仓库中进行跟踪：

    git add <file name>

例如：

    git add main.c

### 3.8.1.2 Clone 仓库

更多的时候，不需要手动创建 git 仓库。git 仓库很可能已经存在于远端服务器或别人的计算机中，这时候我们只需要将其 clone 到本地即可：

    git clone <URL>

例如：

    git clone https://192.168.1.8/path/repo.git

git 支持 http、https、ssh 格式的 URL 访问。

### 3.8.1.3 提交变更

在修改代码或相关文件后，需要先将变更缓存到本地，这一步被称作 commit。带签名的提交命令如下：

    git add .
    git commit -s -m "Message"

### 3.8.1.4 时光穿梭

如果文件尚未 stash，可使用 checkout 命令撤回修改：

    git checkout -- <file>

如果文件已 stash 但是没有 commit，可使用 reset 命令撤回修改：

    git reset HEAD <file>

如果文件已经 commit，可使用下列命令：

    git reset --soft <commit id>
    git reset --hard <commit id>
    git reset --hard HEAD~10
    git revert <commit id>

注意 soft 与 hard 的区别主要在于 hard 不保留工作区中的内容，但是 soft 保留工作区中的内容。而 reset 与 revert 的区别在于 revert 是放弃指定提交的修改，但是会生成一次新的提交，需要填写提交注释，以前的历史记录都在，而reset是指将HEAD指针指到指定提交，历史记录中不会出现放弃的提交记录。

### 3.8.1.5 分支管理

通过以下命令创建新的本地分支：

    git branch <branch name>

还可以通过以下命令查看分支情况：

    git branch
    git branch -a

使用下列命令切换到对应分支：

    git checkout <branch name>

删除某分支的命令为：

    git branch -d <branch name>

### 3.8.1.6 查看历史

版本管理提供的最主要的功能之一便是历史追溯，可以查看每一次变更的内容，相关提交的信息等。通过下列命令实现：

    git show

### 3.8.1.7 Tag 节点

可以通过：

    git tag

命令列出当前仓库中的所有标签，创建一个带附注的的标签则可以使用以下命令实现：

    git tag -a <tag name> -m "Message"

还可以使用：

    git tag <tag name>

创建一个轻量标签。

### 3.8.1.8 推送本地分支到远程分支

    git push <repository> <local refspec>:<remote refspec>

如，推送本地的 new 分支与 origin 主机的 master 分支合并：

    git push origin new:master

### 3.8.1.9 从远程分支更新本地分支

    git pull <repository> <remote refspec>:<local refspec>

如，要取回 origin 主机的 new 分支，与本地的 master 分支合并：

    git pull origin new:master

## 3.8.2 Gitea

Git 经常配合 TortoiseGit、VS Code、Git Hub 或 Gitea 等工具使用。Gitea 与 Git Hub 类似，可用于构建 Git 服务器，实现代码托管和项目管理。Gitea 的部署非常容易，使用方式又与 Git Hub 相像，这里以 Git 结合 Gitea 使用为例进行讲解。

以下假设服务器的地址为 <https://192.168.1.8/>。  

### 3.8.2.1 账户管理

下面是一个典型的 Gitea 登陆界面：

![3-8-2-001-Gitea登陆界面](img/3-8/3-8-2-001.jpg)

Gitea 的用户可以自助注册。但为便于服务器的管理，我们的服务器不开放注册功能。用户账号由服务器管理员进行分配和管理。申请服务器账号需要向管理员提供有效的 E-mail 用于完成注册和验证验证。

当 E-mail 邮箱收到注册验证邮件后，点击 “reset your password” 链接修改密码并激活 Gitea 账号。

当密码修改完毕并完成账号激活后，就可以使用申请的邮箱和新密码进行登陆。登陆后通过个人“设置”来修改用户名称和头像。

![3-8-2-002-Gitea用户管理](img/3-8/3-8-2-002.jpg)

### 3.8.2.2 仓库管理

每个账户都可以创建自己的代码仓库（创建仓库的数量有限制，可向管理员申请增加仓库数量）。通过以下两种方式都可以创建一个新的代码仓库。

![3-8-2-003-Gitea创建仓库](img/3-8/3-8-2-003.jpg)

接下来需要配置仓库管理者、仓库名称、仓库可见性、仓库描述、仓库忽略文件的类型模板、软件许可证，以及是否初始化仓库。

![3-8-2-004-Gitea初始化仓库](img/3-8/3-8-2-004.jpg)

在上图中，我们创建了一个私有仓库，git 忽略文件选用了 C++ 项目的模板文件，并由服务器自动初始化好这个仓库。

如果项目是私有的，那么只有仓库“拥有者”和“协作者”可以看到这个代码仓库，其他人不可见；如果项目不是私有的，那么就是一个公开项目，任何人都可以看到这个项目。

git 忽略文件是一个名为 “.gitignore” 的文件，这个文件里是一些会被 git 版本管理系统忽略的文件的名称。C++ .gitignore 模板定义了可用于 C++ 项目的一些可被版本管理忽略的文件名称和类型。

如果没有选中“初始化存储库”选项，那么你需要手动 git init 这个仓库。如果选中了该选项，就不再需要手动 init，并且 gitea 会自动生成项目的 .gitignore 和 README.md 文件。

配置好仓库后，点击“创建仓库按钮”，该仓库即被创建到服务器上。

![3-8-2-005-Gitea空仓库](img/3-8/3-8-2-005.jpg)

复制右侧红框中的连接，之后 git clone 这个连接，即可将 Gitea 服务器上创建的这个项目 clone 到本地。

点击“仓库设置”可进入仓库高级管理界面，在该界面可以修改仓库名称、转移仓库所有权、删除本仓库、设置分支保护等。

### 3.8.2.3 提交和获取变更

将仓库 clone 到本地后，可以任意修改，之后在本地进行 commit 操作，最后使用 git push 命令将修改提交到 Gitea 服务器。

如果 Gitea 服务器上该项目内容被别人修改了，我们可以使用 git pull 命令对本地仓库进行更新。

如果在你提交代码前，服务器上的代码已经发生了变化，那么你的提交会被禁止。这时候需要先从服务器获取更新，然后在本地 Merge 代码，之后再进行提交。

### 3.8.2.4 代码 Review

代码 Review 是软件开发过程中一项非常重要的工作，任何人都不应该随意的提交代码到软件仓库中，只有哪些经过专家评审过的代码才能被提交到正式仓库中。其他开发代码可以只存储到临时分支里。当开发代码足够成熟后，再发起向主干分支的合并请求。

Gitea 对代码 Review 的支持也是基于这样的理论指导。

![3-8-2-006-Gitea分支保护](img/3-8/3-8-2-006.jpg)

在“仓库设置”中的“分支列表”里选择要保护的分支作为主干分支，Gitea 禁止对受保护的分支进行 push 操作。开发人员需要创建一个新的分支进行开发，开发完成后，基于新的分支发起 Merge 请求。仓库管理员会获得通知，并基于这个 Merge 请求进行代码 Review。如果代码合格，合并请求将会被通过，如果代码不合格，仓库管理员可以拒绝进行 Merge 操作。Merge 请求通过后，新的代码将被合并到主干代码中。

![3-8-2-007-Gitea分支保护白名单](img/3-8/3-8-2-007.jpg)

开发人员在仓库的 “合并请求” 中发起 Merge 请求。

![3-8-2-008-Gitea创建合并请求](img/3-8/3-8-2-008.jpg)

如果开发者发起了 Merge 请求，仓库管理者将收到通知，并在“合并请求”中看到该提交。
![3-8-2-009-Gitea合并请求](img/3-8/3-8-2-009.jpg)

仓库管理者可以选择拒绝该请求或通过该请求。

![3-8-2-010-Gitea通过合并请求](img/3-8/3-8-2-010.jpg)

如果合并没有冲突，则系统进行自动合并，如果存在合并冲突，则需要仓库管理者手动合并。

### 3.8.2.5 版本发布

点击“版本发布”中的“发布新版”按钮，选择要发布版本的分支，添加标签名称，标题和内容，服务器将基于所选择分支的最新提交发布新的软件版本。

![3-8-2-011-Gitea版本发布](img/3-8/3-8-2-011.jpg)

### 3.8.2.6 发起 Issue 讨论

如有由需要讨论的话题或软件 Bug，则可以发起 Issue，可以为 Issue 设置标签，Issue 也可以被里程碑管理。

在“工单”中点击“创建工单”，填写标题和内容，选择分支、标签、里程碑、指派成员。

![3-8-2-012-Gitea创建Issue](img/3-8/3-8-2-012.jpg)

被指派的成员将获得通知，并按照要求对 Issue 进行处理，其他人员可在工单系统中以对 Issue 进行评论或讨论，还可以为 Issue 设置截止时间。

还可以在“工单”对 Issue 进行搜索，筛选等。

如果一个工单已完成，需要将其关闭。

### 3.8.2.7 项目百科

项目经常会由一些资料或说明文档，这些资料可以被 Gitea 的百科系统进行管理。单击“百科”中的“创建第一个页面”

![3-8-2-013-Gitea创建百科](img/3-8/3-8-2-013.jpg)

之后就可以在“百科”中看到这些资料文档了。开发者还可以添加新的百科页面，也可以删除已存在的页面。

### 3.8.2.8 组织管理

如果多个开发者共同开发一个大的项目，这个项目由几个软件仓库构成，那么可以用“组织管理系统”管理这些开发者和软件仓库。可以通过以下两种方式来创建组织：

![3-8-2-014-Gitea创建组织](img/3-8/3-8-2-014.jpg)

之后输入组织名称，完成组织创建。点击右上角的按钮，进入该组织。

![3-8-2-015-Gitea进入组织](img/3-8/3-8-2-015.jpg)

点击组织旁边的齿轮按钮对组织进行设置，可以修改组织名称、设置组织头像、删除组织等。也可以通过团队管理对组织团队进行管理。

![3-8-2-016-Gitea组织设置](img/3-8/3-8-2-016.jpg)

通过“新建团队”按钮，你可以新建一个团队，设定团队对组织中仓库的访问权限，添加或删除团队成员。

![3-8-2-017-Gitea团队管理](img/3-8/3-8-2-017.jpg)

### 3.8.2.9 协作开发

如果几个开发人员共同开发同一个项目，需要将这些人员添加到项目协作者中：

![3-8-2-018-Gitea添加协作者](img/3-8/3-8-2-018.jpg)

私有仓库会对协作者公开。此时仓库拥有者成为主要管理者，可以对协作人员的访问权限进行设置，也可以将仓库转移给某个协作者，转移后的协作者成为仓库新的拥有者，拥有对仓库的全部访问和配置权限。

## 3.8.3 Meld 差分工具

软件开发人员经常使用差分工具对文件或项目进行比对，以分析对源代码进行了哪些修改。

![3-8-3-001-Meld](img/3-8/3-8-3-001.jpg)

Meld 是常用的开源差分工具，打开需要比较的两个文件或项目文件夹，Meld 将有差异的部分通过高亮显示出来。你可以将一侧的修改移动到另一侧，也可以随意修改打开的文档。

Meld 的使用非常简单，也可以在 Meld 官网获得更详细的帮助。

## 参考

[Pro Git](https://git-scm.com/book/zh/v2)

[Git Reference Manual](https://git-scm.com/docs)

## 练习

在 Gitea 上开通自己的账户，并创建一个 Public 的项目，向该项目提交一份能编译通过的 Cpp 代码，并 Release 为 v1.0，创建一个 Issue 讨论。