选择要操作的路由

当您运行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 谓词，通常在 $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 运行命令。

在成功执行整理或代码清理命令的情况下，precious会隐藏它运行的命令的所有标准输出（stdout）。如果命令以某种方式失败，precious将打印出命令的stdout和stderr输出。

默认情况下，precious将任何输出到stderr视为命令的错误（而不是代码清理失败）。您可以使用ignore-stderr指定一个或多个允许的stderr输出正则表达式。

此外，您可以通过以--debug模式运行precious来查看命令的所有stdout和stderr输出。

总的来说，在quiet模式下运行命令对于precious来说没有价值。这样做只会使得在代码清理失败或其他问题发生时调试该命令变得更加困难。

退出代码

在--tidy模式下运行时，如果整理过程中没有错误，precious始终以0退出，无论是否整理了任何文件。

在--lint模式下运行时，如果所有文件都通过了代码清理，precious将以0退出。如果任何代码清理命令失败，它将以1退出。

在这两种模式下，如果任何命令失败（无论是通过返回非列表中的退出代码，还是意外地打印到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作为提交钩子运行

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

您想要以特定顺序运行命令

截至版本0.1.2，命令的运行顺序与配置文件中出现的顺序相同。

构建状态

构建和测试

Cargo审计夜间

Cargo审计推送到