Nomgen: 不 修改 生成

Nomgen 是一个工具，可以帮助您根据命令生成文件，并在 pre-commit git 钩子中保护生成的文件免受手动修改。

功能

• 使用 TOML 格式的配置文件定义文件生成器。
• 根据配置的命令自动生成和修改文件。
• 运行检查以确保与配置的模式匹配的文件没有手动修改。
• 与 Git pre-commit 钩子集成，在提交之前进行自动化检查（除非由 nomgen 本身进行提交）。

安装

要安装 Nomgen，请确保您已安装 Rust 和 Cargo，然后运行

cargo install nomgen

配置

Nomgen 使用配置文件（nomgen.toml）来定义文件生成器和检查模式。以下是一个配置示例

[[generators]]
command = "protoc --rust_out=experimental-codegen=enabled,kernel=upb:. foo.proto"
patterns = [ "*.pb.rs" ]

[[generators]]
command = "cargo run -- generate-hook"
patterns = [ "pre-commit-hook.*" ]

使用方法

Nomgen 提供了几个命令来管理文件生成和检查

nomgen generate [选项] 根据指定的配置生成或修改文件。

命令将首先检查是否存在手动修改，只有当存储库状态有效时，才会运行生成器。

选项

-c, --config <文件>：TOML 格式配置文件的路径（默认：自动定位最近的 nomgen.toml）。示例

nomgen generate -c nomgen.toml

nomgen 钩子[选项]

生成 Git pre-commit 钩子以在提交之前强制进行检查。

选项

-t, --target <目录>：钩子脚本的目标目录（默认：自动定位最近的 .git/hooks）。示例

nomgen hook -t .git/hooks

nomgen 检查[选项]

检查工作目录中的文件是否包含受保护的模式的修改。

命令会验证所有与 nomgen.toml 中配置的模式匹配的文件 - 已暂存或未暂存。如果找到任何修改，则退出并返回错误代码 1。通常应从钩子中调用，但也可以手动调用以进行故障排除。

选项

-c, --config <文件>：TOML 格式配置文件的路径（默认：自动定位最近的 nomgen.toml）。示例

nomgen check -c nomgen.toml

入门

您应该从安装钩子开始，在您的存储库中运行 nomgen hook。

然后通过指定生成器来设置 nomgen.toml 文件。

每个生成器都可以有一个用于生成内容的命令。除了命令之外，您可能还想设置一个模式来匹配生成的文件，以防止手动编写。

可以有一个只包含命令的生成器 - 如果您不介意防止手动编写。您也可以有一个只包含模式的生成器，如果您不想将生成调用委托给 nomgen，但仍想使用它来定位不需要的更改。

因此，以下所有 nomgen.toml 示例都是有效使用

[[generators]]
# Configures `nomgen generate` to run protoc 
command = "protoc"
args = ["--rust_out=experimental-codegen=enabled,kernel=upb:.", "foo.proto"]
# Configures `nomgen check` and `nomgen generate` to prevent accidental changes to files ending on `.pb.rs`
patterns = ["*.pb.rs"]

[[generators]]
# Configures `nomgen generate` to run protoc 
command = "protoc"
args = ["--rust_out=experimental-codegen=enabled,kernel=upb:.", "foo.proto"]
# No pattern config, no protection from manual changes

[[generators]]
# Configures `nomgen check` and `nomgen generate` to prevent accidental changes to files ending on `.pb.rs`
patterns = ["*.pb.rs"]
# No command to use during `nomgen generate` 

# Generator for protobuf things
[[generators]]
# Configures `nomgen generate` to run protoc 
command = "protoc"
args = ["--rust_out=experimental-codegen=enabled,kernel=upb:.", "foo.proto"]
# Configures `nomgen check` and `nomgen generate` to prevent accidental changes to files ending on `.pb.rs`
patterns = ["*.pb.rs"]

# Generator for nomgen hook
[[generators]]
command = "nomgen"
args = ["hook", "-d", ".husky"]
patterns = [".husky/pre-commit"]

# Some other generators could follow
# [[generators]]
# ...

使用 husky 吗？

是的，上面的例子显示，如果您的设置包括已提交到存储库的钩子，那么生成 nomgen 钩子就属于 nomgen 作为其自身生成器之一的使用场景。这是一个有效场景，但请注意不同用户可能有不同版本的 nomgen - 这可能导致钩子不断重新生成。

当然，如果您想在 pre-commit 中完成多件事情，您可能想这样做

# Generator for nomgen hook
[[generators]]
command = "nomgen"
args = ["hook", "-d", ".husky", "-h", "pre-commit-nomgen"]
patterns = [".husky/pre-commit-nomgen"]

# Add some more generators
# ...

这会在 pre-commit-nomgen 文件中生成 nomgen 钩子，该钩子不会被 git 调用，这意味着现在在 pre-commit 中您会有类似以下内容

#!/bin/bash

set -e
DIR="$( dirname "${BASH_SOURCE[0]}" )"
sh "${DIR}/pre-commit-nomgen"

# Add other checks that should be run before commiting here
# ... yarn test
# ... yarn prettier

因此，现在您有一个设置，当您调用 nomgen generate 时会自动生成 nomgen 钩子，就像运行任何其他生成器一样。该钩子可以保护您免受对自动生成文件（包括 nomgen 钩子本身）的手动更改，同时您仍然可以在提交之前执行其他检查，而 husky 则负责配置 git 使用您的钩子。

其中一个例子设置了此功能，并增加了一个额外功能 - 它不是调用 check（默认），而是配置钩子调用 generate。这强制 nomgen 在提交之前重新生成文件，如果您想确保不提交过时的文件，这非常有用。

在钩子中生成吗？

运行 nomgen hook -c generate 可以得到在提交之前重新生成文件的钩子。如果您想确保不提交过时的文件，这很有用。nomgen 足够聪明，知道在这种情况下生成不会创建提交，只会暂存生成的更改，因此触发钩子的提交将包括这些更改。

以下是一个变体配置，它将 nomgen generate 配置为在 .husky/pre-commit-nomgen 文件中创建此类生成钩子

[[generators]]
command = "nomgen"
args = ["hook", "-d", ".husky", "-h", "pre-commit-nomgen", "-c", "generate"]
patterns = [".husky/pre-commit-nomgen"]

因此，稍后您可以从 husky 控制的 pre-commit 调用该脚本，如上所述。