命令的运行顺序与它们在配置文件中出现的顺序相同。

命令调用

有三个配置键用于命令调用。它们都是可选的。如果没有指定任何键，precious将默认使用以下配置

invoke      = "per-file"
working-dir = "root"
path-args   = "file"

这将在每个文件上运行一次命令，命令的工作目录是项目根目录。命令将作为单个参数传递给命令，参数是相对于根目录的文件相对路径。

invoke

invoke键告诉precious如何调用命令。

invoke键还有一些实验性选项。 它们的确切名称或如何操作的具体细节可能在未来的版本中更改。

它们是这样写的

[commands.some-command]
invoke.per-file-or-dir = 42

这些实验性选项有助于优化命令的运行速度。在某些情况下，命令可以以多种方式运行，而完成速度取决于需要检查或整理的文件或目录数量。

例如，golangci-lint工具。对几个目录多次调用它可能比对其整个仓库运行要快得多。然而，一旦有足够的目录进行检查，对整个仓库运行一次将更快。

请注意，path-args设置需要与这些选项的两种可能情况一起工作。对于golangci-lint来说，这意味着在使用per-dir-or-once时将其设置为dir。

工作目录

工作目录键告诉 precious 命令运行时的工作目录应该是什么。

working-dir.chdir-到= "路径"

工作目录的最终选项是将显式路径设置为工作目录。

使用此选项，当命令执行时，工作目录将设置为给定的子目录。传递给命令的相对路径将相对于此子目录，而不是项目根目录。

path-args

path-args键告诉 precious 在运行命令时如何传递路径。

不合理的组合

这些配置键的大多数组合都是允许的，但有一些不合理的组合会导致 precious 以错误退出。

invoke = "per-file"
path-args = "dir", "none", "dot", or "absolute-dir"

如果您不传递文件名，则无法为每个文件调用一次命令。

invoke = "per-dir"
path-args = "none" or "dot"
working-dir = "root"
# ... or ...
working-dir.chdir-to = "whatever"

如果您从根目录调用一次命令而未传递目录名或文件名列表，则无法调用一次命令。如果您想使用没有路径参数或使用 . 作为路径的 . 来运行一次目录中的命令，则 必须 将 working-dir = "dir" 设置为。

invoke = "once"
working-dir = "dir"

如果将工作目录设置为每个匹配的目录，则无法调用一次命令。

调用示例

有关每个可能的选项集的完整示例，请参阅调用示例文档。

每个命令的其他配置键

每个命令允许的其他键如下

引用项目根目录

对于可以从子目录运行的命令，您可能需要以项目根目录的术语指定配置文件。您可以通过在cmd配置键的任何元素中使用字符串$PRECIOUS_ROOT来做到这一点。例如，您可能写成这样

cmd = ["some-tidier", "--config", "$PRECIOUS_ROOT/some-tidier.conf"]

字符串$PRECIOUS_ROOT将被替换为项目根目录的绝对路径。

运行Precious

要获取帮助，请运行precious --help。

根命令接受以下标志

并行执行

Precious 将始终并行执行命令，默认情况下每个CPU一个进程。执行是基于命令的调用配置并行化的。例如，在12个CPU的系统上，具有 invoke = "per-file" 的命令将并行执行多达12次，每个命令执行接收一个文件。

通过传递 --jobs 1 可以禁用并行执行。

子命令

precious 命令有三个子命令，lint、tidy 和 config。您必须始终指定其中一个。 lint 和 tidy 命令接受相同的标志

选择操作路径

当您运行 precious 时，必须告诉它要操作哪些路径。为此有几个标志

运行单个命令

通过传递 --command 标志，您可以使用单个命令进行整理或检查

$> precious lint --command some-command --all

传递给 --command 的名称必须与您的配置文件中的命令名称匹配。因此，在上面的示例中，这将查找配置中定义的 [commands.some-command] 命令。

使用标签选择命令

每个命令可以分配一个或多个标签。这允许您创建任意命令组。然后当您整理或检查时，可以通过传递一个 --label 标志来选择一个标签

$> precious lint --label some-label --all

标签的工作方式如下

• 没有在配置中包含 labels 键的命令有一个标签，即 default。
• 在不传递 --label 标志的情况下运行 tidy 或 lint 使用 default 标签。
• 如果您为命令分配了 labels 并希望该命令包含在 default 标签中，则必须明确包含它

  [command.some-command]
  # ...
  labels = [ "default", "some-label" ]
  

默认排除项

在选择路径时，precious 始终 尊重您的忽略文件。目前，它只知道这是如何为 git 工作的，并且将尊重以下所有忽略文件

• 目录级别的 .ignore 和 .gitignore 文件。
• .git/info/exclude 文件。
• 全局 gitignore globs，通常位于 $XDG_CONFIG_HOME/git/ignore。

这是使用 rust ignore crate 实现的，因此应在那里提出对其他 VCS 系统的支持。

此外，您可以通过设置全局 exclude 键为所有命令指定排除项。

最后，您可以为每个命令指定 include 和 exclude 键。

如何应用包含和排除

当 precious 运行时，它会执行以下操作以确定哪些命令适用于哪些路径。

• 要操作的基本文件是根据指定的命令行标志选择的。这包括以下之一：
  • --all - 项目根目录（包含 precious 配置文件的目录）下的所有文件。
  • --git - git 仓库中已修改的所有文件，包括已暂存的文件。
  • --staged - git 仓库中已暂存的所有文件。
  • --git-diff-from <REF> - 当前 HEAD 与 <REF> 不同的所有文件。
  • CLI 上传递的路径 - 如果路径是一个文件，则直接添加到列表中。如果路径是一个目录，则找到该目录下的所有文件（递归）。
• 将 VCS 忽略规则应用于从列表中删除文件。
• 将全局排除规则应用于从列表中删除文件。
• 根据命令的 invoke 键，生成要检查的文件列表，并应用命令的包含/排除规则。要包含，文件必须至少匹配一个包含规则 并且 不匹配任何排除规则才能被接受。
  • 如果 invoke 是 per-file，则逐个文件应用规则。
  • 如果 invoke 是 per-dir，则如果目录中的任何文件匹配规则，则在该目录上运行该命令。
  • 如果 invoke 是 once，则一次性应用规则到所有文件。如果这些文件中的任何一个匹配包含规则，则运行该命令。

config 子命令

除了 init 子命令外，该命令还有一个 list 子命令。它会打印一个 Unicode 表格，描述配置文件中的命令。

Found config file at: /home/autarch/projects/precious/precious.toml

┌─────────────────────┬──────┬────────────────────────────────────────────────────────┐
│ Name                ┆ Type ┆ Runs                                                   │
╞═════════════════════╪══════╪════════════════════════════════════════════════════════╡
│ rustfmt             ┆ both ┆ rustfmt --edition 2021                                 │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ clippy              ┆ lint ┆ cargo clippy --locked --all-targets --all-features     │
│                     ┆      ┆ --workspace -- -D clippy::all                          │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ prettier            ┆ both ┆ ./node_modules/.bin/prettier --no-config --print-width │
│                     ┆      ┆ 100 --prose-wrap always                                │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ omegasort-gitignore ┆ both ┆ omegasort --sort path --unique                         │
└─────────────────────┴──────┴────────────────────────────────────────────────────────┘

配置建议

以下是一些有关如何获得 precious 最佳体验的建议。

选择如何 invoke 命令

一些命令可能在 invoke 设置为 per-dir 或 once 时效果相同。正确的运行模式取决于您如何使用 precious。

一般来说，如果您有非常少的目录，或者 您同时运行 precious 大多数或所有目录，则 once 会更快。

但是，如果您有较多的目录，并且通常只需要一次性检查这些目录中的小部分，则 per-dir 模式会更快。

您还可以使用实验性的 invoke.per-dir-or-once = n 选项，根据 precious 将要操作的目录数量以两种方式之一调用命令。

命令的静默标志

许多命令将接受某种类型的“静默”标志。一般来说，您可能 不 希望以静默模式运行 precious 的命令。

在 tidying 或 lint 命令成功执行的情况下，precious 已经隐藏了它运行的所有命令的 stdout。如果命令以某种方式失败，precious 将打印出命令的 stdout 和 stderr 输出。

默认情况下，珍贵的小吃会将所有输出到stderr的错误视为命令错误（而不是linting失败）。您可以使用ignore-stderr指定一个或多个正则表达式，以指定允许的stderr输出。

此外，您可以通过运行珍贵的小吃在--debug模式下查看命令的所有stdout和stderr输出。

总的来说，在珍贵的小吃中运行命令的静默模式通常没有价值。这样做只会使在lint检查失败或其他问题发生时调试该命令的问题变得更加困难。

退出代码

在--tidy模式下运行时，如果tidying过程中没有错误，珍贵的小吃将始终以0退出，无论是否对任何文件进行了tidying。

在--lint模式下运行时，如果所有文件都通过了linting，珍贵的小吃将退出0。如果任何lint命令失败，则将退出1。

在这两种模式下，如果任何命令失败，无论是返回未列出的ok退出代码还是意外打印到stderr，则退出代码将不会是0或1。

常见场景

有些配置场景您可能需要处理。以下是一些示例

命令在整个源树中只运行一次

一些命令，如rust-clippy，期望在整个源树中只运行一次，而不是每个文件或目录运行一次。

为了实现这一点，您应该使用以下配置

include = "**/*.rs"
invoke = "once"
path-args = "dot" # or "none"

这将导致precious在项目根目录中精确地运行一次命令。

命令在其lint的文件所在的同一目录中运行，并且不接受路径参数

如果您想在不将操作的路径传递给命令的情况下运行命令，请设置invoke = "per-dir"，working-dir = "dir"，和path-args = "none"

include     = "**/*.rs"
invoke      = "per-dir"
working-dir = "dir"
path-args   = "none"

您想排除一个目录（树）中的整个目录（除了一个或多个文件）

在exclude列表中使用以!开头的忽略模式

[commands.rustfmt]
type    = "both"
include = "**/*.rs"
exclude = [
    "path/to/dir",
    "!path/to/dir/included.rs",
]
cmd     = ["rustfmt"]
lint-flags = "--check"
ok-exit-codes = [0]
lint-failure-exit-codes = [1]

您想将珍贵的小吃作为提交钩子运行

只需在您的钩子中运行precious lint -s。如果任何lint命令指示linting问题，则它将以非零状态退出。

您想按特定顺序运行命令

从版本0.1.2开始，命令的运行顺序与它们在配置文件中出现的顺序相同。

构建状态

构建和测试

Cargo Audit 夜间

Cargo Audit 推送时