应该在版本控制中存储哪些文档以及如何存储它们?

时间:2009-03-03 22:23:02

标签: git version-control documentation wiki diagram

我发现了一些类似的问题(hereherehere),询问是否将文档存储到版本控制中。我有一个更具体的要求和一般性问题。具体要求是我想使用Git。更一般的问题是,如何将文档(用于项目的设计,测试,一般实践,技巧等)存储在Git中?更广泛地说,应该存储哪些文件?

我可以想到几个方法:

  1. Word / Open Office文档。新的Office Word具有docx格式,它可以压缩文档,但它也有一个解压缩的XML格式,可用于在Git中有效地存储差异。尽管如此,diff功能仍然被打破,因为XML被压缩在一条线上。这并不比将二进制文件存储到Git中好。
  2. 维基。那里存在什么分布式维基?这就像某种Latex事情,文档被编写和编译/视为维基。
  3. 乳胶 - 但从用于纸张我发现它非常不适合文件。是否有相同的文档? (如何编写手册页?)
  4. 纯文本格式,但由于缺少图表而缺乏这一点,这引起了另一个观点。
  5. 应如何存储视觉效果?他们首先应该创作什么?我正在Linux环境中开发,但项目中的其他一些参与者都在Windows上。哪种跨平台解决方案类似于Visio?当然,它不应该创建存储到Git中的二进制文件。那怎么会与文件相关呢? (例如,类似于Latex在编译时可以引用其他图表的方式。)

7 个答案:

答案 0 :(得分:8)

在决定选择哪种文档格式时,您应该确保团队成员(或者您是独自工作?)能够轻松使用格式本身。

  1. 存储不是问题,因为能够看到版本和合并之间的差异。根据我的经验,没有什么比在任何文本编辑器中可以自由编辑的文本格式更好。这不包括HTML和任何基于XML的格式。 DocBook几乎不可用。

  2. 可以使用任何流行版本控制系统并以分布式方式设置的好wiki是IkiWiki。使用IkiWiki,标记解析在插件中完成,因此您可以基于每个文档选择输入格式。 “默认”,Markdown非常接近纯文本格式。

  3. 如果您对使用LaTeX不满意,请不要使用它。我认为这不适合做快速笔记。手册页是用nroff编写的,但很多人使用其他格式,例如POD

  4. 一些努力成为Visio替代品的项目是Kivio(KDE)和Dia(Gtk / Gnome)。我没有使用Visio本身,所以我无法评论他们的功能集。它可能取决于您想要创建的视觉/图表类型。 UML?流程图?

答案 1 :(得分:6)

我的公司在Word中存储Word文档,并通过TortoiseSVN访问它们。

Tortoise使用Word内置的更改跟踪功能向您显示两个修订版的“差异”。

这非常有效,但需要Windows和Word。

修改

你可能也可以使用git。如果你安装了TortoiseSVN,那么看看%PROGRAMFILES%\TortoiseSVN\Diff-Scripts\,你会看到乌龟正在做什么。

如果您正在使用git,我认为您已足够1337来破解它为您工作:)

答案 2 :(得分:2)

对于Word文档,请尝试使用RTF(富文本格式),这基本上是文本。另一种可能性是HTML。它们是文本,所以你应该能够对它们进行差异化。

大多数Wiki的分发版本都是为了协作而设计的。我想你真的在问是否有托管解决方案,或者你是否需要管理它们。看看http://www.atlassian.com/

答案 3 :(得分:1)

Git可以处理二进制文件以及文本文件。 Git不是显式存储差异,而是将整个以前的文件修订版存储在存储库中。然后压缩存储库对象以节省空间。每当你要求时,差异就会被重建。

因此,仅考虑磁盘空间,在Git中存储未压缩的XML Office文档与存储同一文档的压缩版本之间几乎没有区别。唯一的区别是Zip与Git选择使用的压缩的相对性能。

答案 4 :(得分:1)

大多数文档格式在源代码控制方面都不能很好地发挥作用。您列出的几乎所有内容都要么是有效的二进制格式,要么是错综复杂的标记。只要您只需要文档版本而不关心差异,就可以使用您喜欢的任何格式。我更喜欢Microsoft Word文档,因为您可以使用内置的更改跟踪和注释系统来跟踪文档之间的增量。

至于要存储的文件,我建议您存储以后可以使用的任何文件。如果你离开,有人可以使用哪些文件来继续项目?哪些文件有助于让新人加快速度?这意味着规格,但不是燃尽图等文件。

要回答问题的维基部分,请查看DokuWiki。它将所有内容存储在文本文件中,以便将它们添加到源控制系统中。

答案 5 :(得分:1)

我刚接触到这样一个事实:我无法通过版本控制系统跟踪对二进制文件格式的更改,但我仍然使用它,因为它很有用。请注意,通常大多数此类文件都是将要发布的工作产品(用户指南,文档等)。

对于像需求和初始设计这样的早期项目工件,我倾向于使用文本文档 - 不是因为我可以跟踪更改,而是因为我喜欢使用我的IDE。

我从来没有因为版本控制中无法“改变”这一事实而被“咬”。有关更改重要二进制文档的提交注释和其他文档指南通常可以弥补缺乏可见性 - 如果您查找它,则会有另一条路径。

我同意这不太理想,但我认为这不值得担心。

也许我已经习惯了一组文件的想法,我可以跟踪我想要的内容。

我在版本控制中投入了很多,但也使用缺陷跟踪来处理暂时生命周期的一些事情。

答案 6 :(得分:0)

对于OOo,word文档和其他二进制文件,你应该看看pro-git http://git-scm.com/book/ch7-2.html