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

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

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

  • 文件按照分类放在不同的目录里,使用编辑器(如:MS Word)打开文档进行编辑。

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

于是,出现了这种目录结构:

Doc as Code (4):使用Git做版本管理,而不是使用目录做版本管理_第1张图片

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

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

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

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

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

- 1 -

分支

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

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

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

- 2 -

分支的使用

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

1. 为产品初始编写文档

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

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

Doc as Code (4):使用Git做版本管理,而不是使用目录做版本管理_第2张图片

2. 当1.0版本完成定稿

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

Doc as Code (4):使用Git做版本管理,而不是使用目录做版本管理_第3张图片

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

3. 当1.1版本完成定稿

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

Doc as Code (4):使用Git做版本管理,而不是使用目录做版本管理_第4张图片

4. 当2.0版本完成定稿

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

Doc as Code (4):使用Git做版本管理,而不是使用目录做版本管理_第5张图片

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

- 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分支,我们可以看到这个分支上所有文件的所有历史提交记录(从最初加入文件开始)。

Doc as Code (4):使用Git做版本管理,而不是使用目录做版本管理_第6张图片

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

Doc as Code (4):使用Git做版本管理,而不是使用目录做版本管理_第7张图片

(红色代表删除的行,绿色代表增加的行)

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

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

通过GongZongHao搜索“大龙谈智能内容”联系我们。

你可能感兴趣的:(Doc,as,Code,DocAsCode)