Git中保留旧版本文档提交历史的实现方法

问题背景 #

我们的代码仓库里有多份随版本迭代更新的文档，现在打算在仓库的HEAD提交中保留文档的历史版本，所有新旧版本文档都放在原doc/目录的子文件夹里。但直接复制粘贴不同历史节点的文档会丢失提交历史，还会产生大量冗余差异，需要找到能保留旧版本文件提交历史的方法。

最小复现示例 #

1. 创建第一个版本的文档 #

$ git init
$ mkdir doc
$ touch doc/index.html
$ echo "<h1>Hello world!</h1>" >> doc/index.html
$ git add doc/index.html
$ git commit -m "init"
$ echo "<p>This package allows you to...</p>" >> doc/index.html
$ git commit -a -m "basic docs"
$ git tag 1.0

此时提交历史：

$ git blame doc/index.html
commit 0: doc/index.html "<h1>Hello world!</h1>"
commit 1: doc/index.html "<p>This package allows you to...</p>"

2. 编写第二个版本的文档 #

$ echo "<p>New feature: ...</p>" >> doc/index.html
$ git commit -a -m "document new feature"
$ git blame doc/index.html
commit 0: doc/index.html "<h1>Hello world!</h1>"
commit 1: doc/index.html "<p>This package allows you to...</p>"
commit 2: doc/index.html "<p>New feature: ...</p>"

3. 迁移当前版本到子文件夹 #

$ mkdir doc/1.0 doc/2.0
$ git mv doc/index.html doc/2.0/index.html
$ git blame doc/2.0/index.html
commit 0: doc/2.0/index.html "<h1>Hello world!</h1>"
commit 1: doc/2.0/index.html "<p>This package allows you to...</p>"
commit 2: doc/2.0/index.html "<p>New feature: ...</p>"

此时需要添加doc/1.0/index.html并保留其原提交历史。

解决方案步骤 #

1. 先提交当前的移动操作：

$ git commit -m "move latest docs to doc/2.0"

2. 使用git update-index将指定版本的文件添加到仓库，同时保留历史关联：

$ git update-index --add --cacheinfo 100644 $(git rev-parse 1.0:doc/index.html) doc/1.0/index.html

• 这个命令直接将标签1.0对应的doc/index.html文件对象添加到当前索引，Git会识别该文件与原文件的历史关联，而非视为全新文件。

3. 提交旧版本文档：

$ git commit -m "add 1.0 version docs with full history"

最终验证 #

完成后，目录结构和历史查询结果如下：

$ tree
.
└── doc
    ├── 1.0
    │   └── index.html
    └── 2.0
        └── index.html
$ git blame doc/1.0/index.html
commit 0: doc/1.0/index.html "<h1>Hello world!</h1>"
commit 1: doc/1.0/index.html "<p>This package allows you to...</p>"

内容的提问来源于stack exchange，提问作者honno