默认排除

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

• 每个目录的.ignore和.gitignore文件。
• .git/info/exclude文件。
• 全局gitignore globs，通常在$XDG_CONFIG_HOME/git/ignore中找到。

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

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

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

如何应用 Include 和 Exclude

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

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

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 运行命令。

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

默认情况下，珍贵的奖励会将任何输出到stderr的内容都视为命令错误（与linting失败相反）。您可以使用ignore-stderr来指定一个或多个允许的stderr输出正则表达式。

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

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

退出代码

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

在--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"

[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]