git 哪些文档应该存储在版本控制中，它们应该如何存储？

What documents should be stored in version control and how should they be stored?

提问by Oliver Zheng

I've found some similar questions (here, here, and here) asking about storing documents into version control. I have a more specific requirement and general question. The specific requirement is that I want to use Git. The more general question is, how should documents (for design, test, general practices, tips, etc, of a project) be stored in Git? More broadly, what documents should be stored?

我发现了一些类似的问题（此处、此处和此处）询问有关将文档存储到版本控制中的问题。我有一个更具体的要求和一般性问题。具体要求是我要使用Git。更普遍的问题是，应该如何将文档（用于项目的设计、测试、一般实践、技巧等）存储在 Git 中？更广泛地说，应该存储哪些文件？

I can think of a few ways:

我可以想到几个方法：

1. Word / Open Office documents. The new Office Word has docx format, which zips up documents, but it also has an unzipped XML format, which could be used to efficiently store diffs in Git. The diff feature is still broken though, since the XMLs are squished on a single line. This is no better than storing a binary file into Git.
2. Wiki. What distributed wikis exist out there? It'd be like some kind of Latex thing where documents are written and compiled / viewed as a wiki.
3. Latex - but from using it for papers I find it pretty unsuitable for documents. Is there a documentation equivalent? (How are man pages written?)
4. Plain text formats, but this is rather lacking due to lack of diagrams, which bring up another point.

1. Word/Open Office 文档。新的 Office Word 具有 docx 格式，可以压缩文档，但它也具有解压缩的 XML 格式，可用于在 Git 中有效地存储差异。diff 功能仍然被破坏，因为 XML 被压缩在一行上。这并不比将二进制文件存储到 Git 中更好。
2. 维基。有哪些分布式维基存在？它就像某种 Latex 的东西，其中文档被编写和编译/作为维基查看。
3. 乳胶 - 但是将它用于文件，我发现它非常不适合用于文件。是否有等效的文档？（手册页是如何编写的？）
4. 纯文本格式，但由于缺少图表，因此相当缺乏，这带来了另一点。

How should visuals be stored? What should they be composed in in the first place? I'm developing on a Linux environment, but some other participants in the project are on Windows. What cross-platform solution is there that resembles Visio? And of course, it should not create binary files to be stored into Git. How then would this tie in with documentation? (E.g. Similar to how Latex can reference other diagrams when compiled.)

应该如何存储视觉效果？它们首先应该由什么组成？我正在 Linux 环境中进行开发，但该项目的其他一些参与者在 Windows 上。有什么类似于 Visio 的跨平台解决方案？当然，它不应该创建要存储到 Git 中的二进制文件。那么这将如何与文档联系起来呢？（例如，类似于 Latex 在编译时如何引用其他图表。）

回答by hillu

When deciding what document format you choose, you should make sure that team members (or are you working alone?) are comfortable working with the format itself.

在决定您选择哪种文档格式时，您应该确保团队成员（或者您是单独工作？）对格式本身感到满意。

1. Storage is not so much the problem as is being able to see diffs between versions and merging. In my experience, nothing beats text formats that can be edited freely in any text editor. This excludes HTML and about any XML-based format. DocBook being a barely usable exception.

2. A good wiki that can use any of the popular version control systems and be set up in a distributed fashion is IkiWiki. With IkiWiki, markup parsing is done in plug-ins, so you can choose input format on a per-document basis. The "default", Markdowngets pretty close to plain-text formats.

3. If you're unhappy with using LaTeX, don't use it. I think it's unsuitable for taking quick notes. Man pages are written in nroff, but many people use other formats such as POD.

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

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

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

Some projects that strive to be alternatives to Visio are Kivio (KDE) and Dia (Gtk/Gnome). I haven't used Visio itself, so I can't comment on their feature sets. It probably depends on what sorts of visuals / diagrams you want to create. UML? Flow charts?

一些努力成为 Visio 替代品的项目是 Kivio (KDE) 和 Dia (Gtk/Gnome)。我没有使用 Visio 本身，所以我不能评论他们的功能集。这可能取决于您想要创建什么样的视觉效果/图表。UML？流程图？

回答by Blorgbeard is out

My company stores Word documents in SVN, and accesses them via TortoiseSVN.

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

Tortoise uses Word's built in change tracking function to show you a "diff" of two revisions.

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

This works really well, but requires Windows and Word.

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

Edit:

编辑：

You could probably get this working with git too. If you install TortoiseSVN, then look in %PROGRAMFILES%\TortoiseSVN\Diff-Scripts\, you'll see what tortoise is doing.

您也可以使用 git 进行此操作。如果您安装 TortoiseSVN，然后查看%PROGRAMFILES%\TortoiseSVN\Diff-Scripts\，您将看到 tortoise 在做什么。

If you're using git, I assume you're 1337 enough to hack it to work for you :)

如果您使用的是 git，我假设您的 1337 足以破解它为您工作:)

回答by Tommy Hui

For Word documents, try using RTF (rich text format), which is basically text. Another possibility would be HTML. They're text, so you should be able to do diffs on them.

对于 Word 文档，尝试使用 RTF（富文本格式），它基本上是文本。另一种可能性是 HTML。它们是文本，因此您应该能够对它们进行差异处理。

Most Wikis are distributed in that they're designed for collaboration. I think you're really asking about whether there are hosted solutions or do you have to manage them. Take a look at http://www.atlassian.com/.

大多数 Wiki 都是分布式的，因为它们是为协作而设计的。我认为您确实在问是否有托管解决方案，或者您是否必须管理它们。看看http://www.atlassian.com/。

回答by Steve Rowe

Most document formats don't play terribly well with source control. Almost everything you list is either effectively a binary format or convoluted markup that won't diff well. As long as you just want versions of documents and don't care about the diff, use whatever format you like. I prefer Microsoft Word documents because you can use the built-in change tracking and comment system to track deltas between documents.

大多数文档格式在源代码管理中都不能很好地发挥作用。您列出的几乎所有内容要么是有效的二进制格式，要么是无法很好区分的复杂标记。只要您只需要文档版本而不关心差异，就可以使用您喜欢的任何格式。我更喜欢 Microsoft Word 文档，因为您可以使用内置的更改跟踪和评论系统来跟踪文档之间的差异。

As for what documents to store, I would recommend storing anything you'll have a use for later. What documents could be used by someone to continue the project should you leave? What documents would be helpful to bring a new person up to speed? This means specifications, but not documents like burndown charts.

至于要存储什么文件，我建议存储任何您以后会用到的东西。如果您离开，某人可以使用哪些文件来继续该项目？哪些文件有助于让新人跟上进度？这意味着规范，而不是像燃尽图这样的文档。

To answer the wiki part of your question, check out DokuWiki. It stores everything in text files so they would be very easy to add into a source control system.

要回答问题的 wiki 部分，请查看DokuWiki。它将所有内容存储在文本文件中，因此很容易将它们添加到源代码控制系统中。

回答by Tim

I've just lived with the fact that I can't track changes to binary file formats through a version control system, but I use it anyway since it is useful. Note that typically most of these types of files are work products that will be released (user guides, docs, etc.)

我刚刚接受了这样一个事实，即我无法通过版本控制系统跟踪二进制文件格式的更改，但我还是会使用它，因为它很有用。请注意，通常这些类型的文件中的大多数是将要发布的工作产品（用户指南、文档等）。

For early project artifacts like requirements and initial designs, I tend to use text documents - not because I can track changes, but because I like to use my IDE for it.

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

I have never really been "bitten" by the fact that a change can't be "diffed" in version control. The commit comments and other documentation guidelines around changing an important binary document usually make up for that lack of visibility - in that there is another trail if you look for it.

我从来没有真正被版本控制中的更改不能“区分”这一事实“咬”。有关更改重要二进制文档的提交注释和其他文档指南通常会弥补这种不可见性——因为如果您寻找它，还有另一条线索。

I agree this is not ideal, but I don't think it is really worth fretting over.

我同意这并不理想，但我认为这真的不值得担心。

Perhaps I just got used to the idea of a set of files I would be able to track as much as I would like.

也许我只是习惯了一组文件的想法，我可以随心所欲地跟踪。

I put a lot in version control, but also use defect tracking for some things with lifespans that are temporary.

我在版本控制方面投入了很多精力，但也对一些具有临时生命周期的事物使用了缺陷跟踪。

回答by Greg Hewgill

Git can handle binary files just as well as text files. Instead of explicitly storing diffs, Git stores the entireprevious revisions of files in the repository. The repository objects are then compressed to save space. Diffs are reconstructed on the fly whenever you ask for them.

Git 可以像处理文本文件一样处理二进制文件。Git 没有显式存储差异，而是在存储库中存储文件的整个先前修订版。然后压缩存储库对象以节省空间。Diffs 会在您要求时即时重建。

So considering only disk space, there is little difference between storing an XML Office document uncompressed in Git, and storing a zipped version of that same document. The only difference would be the relative performance of Zip vs whatever compression Git chooses to use.

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

回答by test

For OOo, word documents and other binary files, you should have a look at pro-git http://git-scm.com/book/ch7-2.html

对于OOo、word文档等二进制文件，你应该看看pro-git http://git-scm.com/book/ch7-2.html