README

providence

一个开发依赖项，安装一些git提交钩子以确保代码风格等。将其添加到composer.json的require-dev中。安全使用dev-master，因为这个项目遵循git-flow，并且只有最新的标记版本会被合并到master中。

    "require-dev" : {
        "robertkosten/providence" : "dev-master"
    }

然后，将安装命令（可选的项目类型）放入你的脚本中（当然，你也可以手动进行安装，但这样你会失去自动安装的优点）

    "scripts" : {
        "post-install-cmd" : [
            "vendor/bin/providence install php-library"
        ],
        "post-update-cmd" : [
            "vendor/bin/providence install php-library"
        ]
    }

如果你指定了项目类型，安装器将确保在项目根目录中放置一个.providence文件，该文件引用了类型。这个文件最终将包含所有你想在项目中强制执行的providence配置选项。

要再次卸载钩子，只需使用./vendor/bin/providence uninstall。

配置 (.providence & git-config)

Providence提供了许多配置选项，可以通过三种方式设置。在优先级最低的是由项目类型或default提供的。可以在项目级别通过在项目根目录放置一个.providence文件来覆盖它们。这两个文件遵循相同的语法，所以如果有疑问，请查看vendor/robertkosten/providence/defaults。虽然概念很简单

# Comments and blank lines work as expected

pre-commit.php.blacklist.list exit|die

在优先级链的最顶层是git-config条目，它们遵循完全相同的命名方案，但以providence.为前缀。

# Setting an option
git config providence.commit-msg.enabled 0

# Removing an option
git config --unset providence.commit-msg.enabled

设置

setup.选项集用于一般设置，如定义默认值setup.default或启用更详细的模式setup.verbose。

文件集

设置的一部分还包括文件集。如果你熟悉ant或phing，你可能会熟悉这个概念。文件集定义了一组globbing表达式，用于识别文件，然后可以使用单个名称引用这些文件。例如，setup.fileset.php \*.php|\*.php5（*需要转义）创建了一个名为php的文件集，它将包含所有以.php或.php5结尾的文件，因此任何特定于php文件的检查（如php-lint）都可以使用它来仅应用于它们（对README.md运行该检查有意义吗？）。

Providence有一个内置的文件集，最初仅用于commit-msg钩子，称为xt-auto（表示“额外”和“自动填充”），它将包含 exactly one file，即包含提交消息的文件（现在你知道git如何让你使用你最喜欢的编辑器在第一个地方输入它了）。对于pre-commit钩子，它包含对/dev/null的引用，因此可以用于触发设计为在整个存储库上运行的模块，如flow-protect-master。

还有一个名为xt-mime-*的文件集组，它们与正常文件集类似配置，但包含MIME类型的globbing表达式（由file -b --mime-type报告）。例如，xt-mime-text被配置为匹配所有text/*文件（在php-library中）。

忽略

与文件集非常相似，忽略指定.globbing模式，这些模式永远不会被任何钩子或模块检查。最明显的例子是.providence文件，例如在指定黑名单时，可以轻松地包含其他文件中禁止的数据。因此，它被添加到默认的providence忽略列表中。如果您检查providence自身的.providence，您将找到另外两个具有类似理由的，一个排除整个默认目录，另一个排除所有包含-error.的测试/files下的文件，因为这些，自然地，对于某些模块是不合法的。

类似于.gitignore处理忽略：尽量少用，并尽可能精确地匹配您的目标集合，以避免不愉快的惊喜。

钩子和模块

所有事物都从enabled开始，这是启用providence部分任何类型处理的高级选项。您会发现所有默认设置（当然，不包括none）都有它，它的目的是在不干扰哪个钩子、文件集和模块造成问题时，快速关闭所有钩子。

大多数东西都分配给一个钩子（当前支持的钩子列表可以从./vendor/bin/providence list中获得），它只是git钩子的名称（我打算尽快支持git flow hooks），例如commit-msg。每个钩子都可以单独开启/关闭，并且像所有的enabled选项一样，默认是关闭的，所以您很可能会在默认设置中看到几个HOOK.enabled条目。

然后是文件集，您可以为其开启/关闭钩子：HOOK.FILESET.enabled。

最后是模块HOOK.FILESET.MODULE.enabled，它可能除了enabled之外还有其他选项，例如debug模块，它支持“安静模式”，通过HOOK.FILESET.debug.quiet开启。这些选项或参数可以是可选的并使用默认值，或者必需的（运行空列表的黑名单是没有意义的）。查看./vendor/bin/providence list -v以了解所有参数和默认值。

示例

一个快速的例子可能会有帮助

setup.fileset.gitignore .gitignore
setup.fileset.php \*.php|\*.php5

enabled 1

commit-msg.enabled 1
commit-msg.xt-auto.enabled 1
commit-msg.xt-auto.format-github.enabled 1

pre-commit.enabled 1
pre-commit.gitignore.enabled 1
pre-commit.gitignore.blacklist.enabled 1
pre-commit.gitignore.blacklist.list .directory|.DS_Store|composer.phar|.buildpath|.project|.settings|.idea
pre-commit.gitignore.whitelist.enabled 1
pre-commit.gitignore.whitelist.list vendor
pre-commit.php.enabled 1
pre-commit.php.php-lint.enabled 1
pre-commit.php.blacklist.enabled 1
pre-commit.php.blacklist.list print_r|var_dump|debug_print_backtrace|eval|md5|sha1|ini_set|exit|die|ereg_|__DIR__|__FILE__|sleep|global|include|?>

这是直接从php-library默认集，它很好地展示了我们的所有功能。首先定义了前两个文件集，gitignore（仅匹配.gitignore文件）和php（匹配以.php或.php5结尾的文件）。然后是全局的enable，以切换providence开启。

接下来是两个钩子的配置，commit-msg和pre-commit。两者作为第一步都是开启的。commit-msg然后使用内置的xt-auto文件集，而pre-commit希望为不同的模块使用我们定义的两个文件集。每个文件集都需要再次开启（精细控制可能会很麻烦）。大多数使用的模块在这种情况下不是很有趣，commit-msg只想检查xt-auto文件是否符合github格式。而pre-commit希望检查和黑名单php文件，并为gitignore提供一个黑名单和白名单。让我们以后者为例：它是开启的，当然，有一个名为list的参数，配置为只包含一个项目vendor。简单来说，这确保了您的.gitignore文件只能在其包含字符串vendor时被提交。

./vendor/bin/providence

除了大量的配置选项外，此脚本还提供了一些小的辅助命令。

开启/关闭

将providence.enabled 1（或0）保存到您本地的git-config的快捷方式。

list

此命令列出providence支持的 所有可用配置选项，通过-v开关可以获得更多信息。

generate

如果您担心我可能会更改您项目类型的默认设置，这个命令会提供将您当前配置（默认设置、.providence 和 git-config）烘焙成一个静态的 .providence 文件（或者可选的任何其他文件名）。但实际上您真的不应该这么做，默认设置一直在不断改进；;-)

clean

添加了半打 git-config 选项，但不想费心去一个个取消设置？使用 clean 命令，所有以 providence. 为前缀的选项将自动从您的 本地 配置中移除。

readme （& 许可证）

想要快速查看文档（或 MIT 许可证），这些命令会快速使用 less 打开它们，这样您就不必自己记住输入 less vendor/robertkosten/providence/README.md。

install / uninstall

Providence 通过 git-hooks 工作并需要放置在 .git/hooks 中。要放置（或移除）这些钩子，这些命令是可用的。这两个命令都不会触碰任何已经存在的文件（但会抱怨任何冲突），尽管任何作为符号链接存在的钩子将被替换为 Providence 的钩子。

安装脚本可选地接受项目类型的名称作为参数（如 composer.json 脚本部分中的示例所示），如果提供，将确保在项目根目录中存在一个 .providence 文件，并且它包含正确的 setup.default PROJECT-TYPE 行（所以如果您切换到静态 .providence，也应该从您的脚本部分中移除项目类型）。

debug

当然，像 providence 这样的复杂小工具这里那里可能有一些错误，如果您想窥视内部，查看实际设置的值，可以使用这个命令。当然，它的输出在发送错误报告时也很有价值。

项目类型 / 默认配置

Providence 为不同的目的提供不同集合的默认配置。这些配置随着时间的推移而扩展和修改，但您可能依赖于它们坚持当前的最佳实践，如由 php-fig、composer 和 Symfony2 所认为的。我会稍微严格一些，所以您必须做出明确的（并在您项目的 .providence 中记录的）决定，以放松对个别选择的控制。例如，Providence 本身之前对在 0.0.4 之前在每次提交信息中要求 github 问题编号更为宽松，但仍然忽略了存在于 defaults/php-library 中的合并标记。

none

默认项目类型和用于生成静态 .providence 的类型。它不包含任何配置，设置为它将从一张白纸开始，Providence 将不会通过其钩子运行任何操作。

php-library

适用于不包含任何（X）HTML、CSS 等，只包含一些 composer 项目中的 php 类的小型 php 库的推荐选项。

shell-project

主要由 shell 代码组成的工具，如 Providence 本身。激活的模块非常少，主要是为了确保编码等。

钩子

Providence 使用的钩子完全是虚拟的，只是具有正确名称的符号链接，因此扩展支持钩子的列表非常简单，唯一的困难是那些需要新方式收集要检查的文件的钩子（目前有 xt-auto 用于 commit-msg，以及其他所有内容）。例如，pre-push 不能与当前代码一起使用。

commit-msg

这个钩子只有在与内置的 xt-auto 文件集一起使用时才有意义，此时它将包含包含提交信息的临时文件。目前只有 format-* 模块与之相关（反之亦然）。

pre-commit

重型工具。它会运行所有您已暂存的文件（无论是通过git add还是git commit -a添加的），通过配置的模块运行，并阻止您提交任何错误的内容。未暂存的变化将被忽略。

模块

模块提供实际的检查，包括列出参数、文档和默认值。大部分关于提供的待办事项都是更多的模块。它们易于编写和测试。加入我们吧！欢迎pull请求 ;-)

使用/vendor/bin/providence list -v获取最新的参数列表及其含义。

黑名单

检查文件中是否有禁止的字符串，例如调试函数、已弃用的功能等。可以选择使用正则表达式，但由于语法原因，只能列出其中一个。

bom（字节顺序标记）

检测以BOM（字节顺序标记）开始的Unicode文件，可以选择要求它。

composer-validate

如果项目根目录中有composer.phar，则使用php composer.phar validate，否则使用composer validate。

debug

一个虚拟模块，可以用来查看任何给定文件集中处理的文件。

编码

确保文件处于合适的编码（如file -b --mime-encoding报告的）。可以配置多个值，这对于通常伪装为us-ascii的utf-8尤其有用，因为它是严格的超集。

flow-protect-master

支持git flow开发模型的一个模块。它旨在防止意外提交到master分支。建议与xt-auto文件集一起使用，以确保它始终被触发。它将忽略任何文件输入，但足够聪明，可以扫描您的git-config以确定是否使用了官方的git flow插件或AVH变体来确定master分支的名称。

format-github

设计用于与commit-msg钩子和xt-auto文件集一起工作（尽管它也可以与任何其他组合一起工作，但不是非常有用）这个模块检查文件内容（即提交信息）是否以对github问题的引用开头，后面跟着一个冒号和一个空格（例如“#1890：添加Lovecraft”）或者遵循github模式来自动关闭问题（例如“Closes #1937 Lovecraft Removed”）。

format-rally

设计用于与commit-msg钩子和xt-auto文件集一起工作（尽管它也可以与任何其他组合一起工作，但不是非常有用）这个模块检查文件内容（即提交信息）是否以对Rally故事的引用开头，后面跟着一个冒号和一个空格（例如“US1890：添加Lovecraft”）。

lineendings

检测到DOS换行符而不是UNIX换行符，可以选择反过来设置。

php-cs

providence的原始目的，一个检查php文件与phpcs的模块。

php-lint

还有什么是比php -l更简单呢？

shell-command

将运行任何任意shell命令，用作许多其他模块（例如php-lint、composer-validate）的基础。

tabs

检测行首的制表符字符，可以选择要求它们。

whitelist

与blacklist相反，这个模块要求一组字符串，例如在.gitignore中排除vendor等。可以选择使用正则表达式，但由于语法原因，只能列出其中一个。

xml-lint

检查文件是否格式良好，但不会将其与DTD或Schema进行验证。

关于

普罗维登斯（Providence）既是“上帝全知之眼”（“全知之眼”的链接）的指代（作为一个无神论者，我只需要观察到在过去我参与的大多数项目中，如果有人能够监视每个人的一举一动将会非常有用。所以我为自己建了一个。），也是黑客文化（《光照派三部曲》的链接）中的引用，以及H.P.洛夫克拉夫特（H.P.洛夫克拉夫特的链接）（他在罗德岛普罗维登斯出生，墓碑上有“我是普罗维登斯”这句话），后者主要是因为我希望这个工具能帮助其他人将微弱的光芒投射进那无尽的混沌深渊，那里潜伏着不可名状的恐怖，它们隐藏在冷漠（软件）宇宙的黑暗之外，被苏布-尼古拉斯的血染红，千子黑山羊，亚亚，普'纳古利·姆格纳法赫·丘布卢·瑞莱赫·瓦哈纳格·弗塔格...

哎呀。我有点失控了 ;-)

致谢

深受Netresearch、克里斯·塞耶、彼得·范·德·多斯和SensioLabs（我在那里没有付费账户，所以从未接触过这个公开可用的列表之外的任何东西）的启发。