6

我正在使用yard来生成我的项目的文档。即使文档可以生成,因此不需要进行版本控制,我们还是决定这样做,因为它可以更容易地查看代码(注释)更改对实际文档的影响。

问题是每次 yard 生成文档时,它都会更改每个文件开头的日期,导致所有文件都被视为已更改。

有没有办法告诉 git 忽略这些行以检测文件是否已更改,或者有一种方法可以将 yard 配置为如果它们相同则不重新生成文件?

谢谢

更新

我知道我可以做一个脚本或其他任何东西,如果只有日期发生了变化,它就会清理文件。所以我的问题是有一种 Git 方法可以做,即我应该费心阅读差异驱动程序还是应该执行干净的脚本。

如果我要走向清理路径,那么使用 git hook 或将其集成到 doc 生成中会更好吗?

最终,我对任何其他方式来跟踪由于生成的文档中的特定提交而导致的更改感兴趣。

我还没有真正解释我的问题是什么(以及为什么我要尝试对不需要的东西进行版本化)所以我们开始了。

有时,代码中的一些修改会搞砸文档,因此我将能够看到提交对文档的影响。

示例:我为 vim 使用模式行(文件第一行的注释告诉 vim 不同的信息)

知道我有一个包含模块文档的文件

#vi: my vim setting 
# Documentation of module A
module A
  .... some code

end

在其他地方我使用这个模块

#vi : my vim setting

           ( 2 blank lines)
module A
   .... some different code
end

那时,一切都很好,A 的文档将是Documentation of module A. 但是,如果有人(比如我)删除了最后一个文件中的一个空行并只留下一个(是的,我在模式行和代码之间留了 2 个空行),那么院子认为模式行是模块 A 的文档,它将是vi : my vim setting.

问题是,除了查看每一页之外,没有办法检测到文档是否被搞砸了。使用 git,我可以快速查看和检查更改的内容,甚至可以找到更改的时间(这很重要,因为这样我就可以找出更改的原因)。

4

6 回答 6

3

不是直接的答案,只有元素:

  • git diff可以-G选择只保留与某个正则表达式匹配的补丁。似乎没有一个标志可以排除与您的日期线匹配的行,但也许您将有足够的想象力来构建一个正则表达式来保留除您的日期线之外的任何内容。
  • diff有这样一个选项 ( diff -I),所以如果你能想办法将 git 生成的 diff 提供给 diff,你就可以走了。
  • meld是一个图形差异查看器,可以很好地与 git 配合使用——例如,在项目目录上调用会meld dir/打开一个窗口,显示所有与HEAD过滤器)。它是为 linux 发行版打包的(至少对于 Ubuntu),并且该网站声称它也可以在 MacOS X 和 Windows 上运行(我没有尝试过)。
  • 我还没有尝试过所有与 git 集成的可用 difftools,但它们可能提供类似的功能。
于 2012-07-06T09:43:50.473 回答
2

我对 yard 不熟悉,但没有办法让 git 忽略文件的某些部分。

最简单的解决方案是修改您的构建过程以运行自定义脚本,该脚本从生成的文件中删除数据,或者如果仅更改日期并在这种情况下恢复日期更改,则检查 git-diff。

但是,根本不对任何生成的代码/文件进行版本控制会更干净。

于 2012-07-05T14:43:41.523 回答
2

不要那样做

可以从源重新生成的资产不应进行版本控制。正是由于您遇到的原因,这是一个坏主意:

  1. 您的历史记录跟踪您不关心的更改。
  2. 您必须努力忽略与您的提交历史无关的琐碎更改。
  3. 您将存储库空间和处理时间浪费在可以按需重新生成的数据上。

请参阅https://stackoverflow.com/a/10855342/1301972,了解有关版本和遗漏内容的相关讨论。

如果你还是这样做...

您可以在 Git 中创建一个自定义的清理过滤器(或在您更新 YARD 时运行的 shell 脚本或 Rake 任务),在您提交文档文件之前删除您的时间戳。例如:

# Tested with: GNU findutils 4.4.2, GNU sed 4.2.1
find doc -type f -iname \*html -exec sed -i '/id="footer"/,/\/div/ d' {} +

这将删除 YARD 文档中的所有页脚,这样您就不会将这些行提交到您的历史记录中。这应该解决您的具体问题。

于 2012-07-10T12:01:18.967 回答
2

文件中完全没有日期就足够了吗?

特定于院子的解决方案(但不是特定于 git),如果您实际上不使用这些日期 - 首先让院子不生成它们:

在其中创建一个空文件,customtemplates/default/layout/html/footer.erb然后将其包含在您的模板中:

  • 使用命令行

    yardoc --template-path ./customtemplates
    
  • 使用 Rakefile

    YARD::Rake::YardocTask.new do |yardoc|
        yardoc.options = ["--template-path", "./customtemplates"]
    end
    

(或者,如果您仍然想要对 Yard 的确认,您可以将以下内容放入customtemplates/default/layout/html/footer.erb文件中)

<div id="footer">
     Generated by <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>.
</div>

或者您可以在自己的页脚中添加公司徽标或其他信息。

于 2012-07-12T02:09:44.507 回答
1

我有几乎同样的问题。这不是文档,而是 IDE 设置更改日期和时间的源文件。每次都保存。

要求是在提交之前让这个日期和时间“相当”,这意味着没有秒,分钟应该四舍五入到 15。

我认为最好的方法是在提交之前创建一个小的 git 命令来清理代码。插件。将其命名git-cleanup并将其放入c:\Program Files (x86)\Git\libexec\git-core(我使用的是 Windows)。

所以现在在做之前git commit我正在跑步git cleanup,它完成了所有的工作。实际上,我认为甚至可以一次性运行它,例如git cleanup && git commit -a -m "Commit message". 或者为此命令创建自定义别名。

我已经用于ruby创建这个小脚本。但是您可以使用您选择的语言。Git 允许这样做。

于 2012-07-06T09:49:23.843 回答
0

更新问题的 Modeline 解决方案

如果问题确实是VIM模式行,而不是页脚中存储的日期,那么您可以使用 pre-commit 钩子(客户端)或 pre-receive 或 post-receive 钩子(服务器端)在之后立即检查换行符模式线。例如,使用 GNU sed:

sed -r '/^#[[:space:]]+vim?:/ {N; /\n[^\n]/q1}'

然后,您的钩子可以显示差异、错误消息或根据退出状态采取其他操作。重要的是您的模式行将与后续文档块正确分离,并且应该被 YARD 正确忽略。

于 2012-07-12T13:10:21.497 回答