Doc as Code (4)：使用Git做版本管理，而不是使用目录做版本管理

▲ 搜索“大龙谈智能内容”关注GongZongHao▲ 

在引入版本管理工具之前，文档工程师使用文件系统提供的功能来管理文件。大家是这样工作的：

• 文件按照分类放在不同的目录里，使用编辑器（如：MS Word）打开文档进行编辑。

• 如果改版，则新创建一个目录并将文件拷贝一份进行编辑。

于是，出现了这种目录结构：

我们把上边这种方法叫做使用目录做版本管理。 

Git是版本管理工具，出来很多年，在软件开发领域得到广泛的应用，已经非常成熟稳定了。

有些文档团队已经使用Git来管理文档。不过，鉴于以前的习惯，将不同版本的文档放在不同目录的方法被沿袭下来。

但是，这种方式只是使用Git来让团队成员协作和共享文档，它并没有很好地利用Git的版本管理的能力。

今天就来说说怎样使用Git更好地进行版本管理。

- 1 -

分支

版本控制系统最初是为软件研发设计的。顾名思义，分支就是从主线上分离出来进行另外的操作，而又不影响主线，主线又可以继续干它的事，最后分支做完事后合并到主线上。

几乎所有的版本控制系统(SVN, Git等）都以某种形式支持分支。实现方式有不同，但是基本思路是一样的。 

通过下边的分支使用的例子，看看怎么用。 

- 2 -

分支的使用

下边是使用分支的一种方法（不是唯一方法）。 箭头方向代表时间向前的方向。 

1. 为产品初始编写文档

创建Git仓库的时候，它有一个默认的分支，这个分支叫做master。

提交的更改都放在master这个分支。 

2. 当1.0版本完成定稿

创建1.0分支，用来记录这一时刻的内容。后续新功能的开发继续提交到master分支上。

为什么要创建分支呢？主要是记录这个时刻的内容，待到将来任何一个时间点都能获取现在的内容。

3. 当1.1版本完成定稿

创建1.1分支，用来记录这一时刻的内容。后续新功能的开发继续提交到master分支上。

4. 当2.0版本完成定稿

创建2.0分支，用来记录这一时刻的内容。后续新功能的开发继续提交到master分支上。

这样最终形成一个像树一样的结构（倒过来的树）。通过这些分支，随时可以取得这些节点的内容。 

- 3 -

分支与目录

可以看到使用Git的分支作为版本，替代了之前用目录作为版本。 在文件系统中，不再有一个1.0, 1.1这样的目录。  

这样做的好处有几点：

1. 支持同时编辑多个版本的内容

假设我们为一个软件编写文档。如上边分支的图，我们已经发布了2.0版本的文档，现在正在编写下一个版本的新功能文档。这时2.0版本发现一个bug，我们需要去2.0版本修改文档然后发布。 

这时我们使用Git的分支切换的功能，切换到2.0这个版本分支。

神奇的地方在于，它将当前工作目录中的内容回退/切换到2.0版本的目录和文件内容。 在创建2.0这个分支这个时间点以后新加的目录、新加的文件都没有了。 （如果切换回master分支，又都有了）

这时候对文档进行改动并提交，这个变更会被放在2.0这个分支上。 

2. 将一个版本的变更合并到另外一个版本上

假设这个bug在最新版中也被修复了，我们只需要将2.0分支上的修改合并到master上，这样为修复这个bug更改的文档内容都会被合并到master上。 

如果使用目录进行版本管理，无法做到合并。我们如果直接将2.0版本的文件覆盖到master上，在master上做的所有更改都将丢失。使用Git的分支合并功能，则不会丢失。 

3. 查看一个文件的所有变更历史

如果当前分支是master分支，我们可以看到这个分支上所有文件的所有历史提交记录（从最初加入文件开始）。

点击进去可以看到这次到底修改了什么：

（红色代表删除的行，绿色代表增加的行）

在使用目录管理版本的情形，则看不到一个文件的所有历史，只能看到当前这个版本的历史。 

原因是我们创建新版是将文件从一个目录拷贝到另外一个目录。拷贝前的文件和拷贝后的文件并没有关联关系，无法追溯。

通过摩拿官网联系我们。