跳到主要内容

配置文件

Watchman 在两个位置查找配置文件

  • 全局配置文件 /etc/watchman.json
  • 根目录特定的配置文件 .watchmanconfig

在监视根目录时，如果根目录下存在名为 .watchmanconfig 的有效 JSON 文件，watchman 将加载它并将其用作特定于该根目录的配置信息的来源。

全局配置路径可以通过在构建 watchman 时传递 --enable-conffile 选项来更改。本文档将其称为 /etc/watchman.json，但请注意，您的特定安装可能会将其放在其他位置。此外，环境变量 $WATCHMAN_CONFIG_FILE 将覆盖默认位置。

如果全局配置文件不存在，Watchman 将回退到附加了 “.default” 的路径（例如 /etc/watchman.json.default）。这允许 Watchman 系统包提供不同的配置默认值，例如将 enforce_root_files 设置为 true。

对 .watchmanconfig 或 /etc/watchman.json 文件的更改不会自动生效；您需要删除并重新添加监视（对于 .watchmanconfig）或重新启动 watchman（对于 /etc/watchman.json）才能使这些更改生效。

解析/作用域​

有三个配置作用域

  • local - 选项值从关联根目录的 .watchmanconfig 文件中读取。
  • global - 选项值从 /etc/watchman.json 文件中读取
  • fallback - 选项值从 .watchmanconfig 文件中读取。如果该选项不存在于 .watchmanconfig 文件中，则从 /etc/watchman.json 文件中读取它。

下表显示了各种选项的作用域和可用性

选项作用域自版本
settlelocal
root_restrict_filesglobal3.1 中已弃用
root_filesglobal3.1
enforce_root_filesglobal3.1
illegal_fstypesglobal2.9.8
illegal_fstypes_adviceglobal2.9.8
ignore_vcslocal2.9.3
ignore_dirslocal2.9.3
gc_age_secondslocal2.9.4
gc_interval_secondslocal2.9.4
fsevents_latencyfallback3.2
idle_reap_age_secondslocal3.7
hint_num_files_per_dirfallback3.9
hint_num_dirsfallback4.6
suppress_recrawl_warningsfallback4.7

配置选项​

settle​

指定以毫秒为单位的 settle 周期。这控制文件系统在分派触发器之前应保持空闲的时间。默认值为 20 毫秒。

root_files​

自 3.1 起。

指定一个文件列表，如果该列表中的文件存在于某个目录中，则将该目录标识为项目的根目录。

如果未指定，为了帮助在版本之间过渡，watchman 将使用现已弃用的 root_restrict_files 配置设置的值。

如果 root_files 和 root_restrict_files 均未在配置中指定，则 watchman 将使用由以下各项组成的默认值

  • .git
  • .hg
  • .svn
  • .watchmanconfig

如果 .watchmanconfig 不存在，Watchman 会将其添加到为此配置值指定的任何值中。

此示例导致仅将 .watchmanconfig 视为项目根文件

{
  "root_files": [".watchmanconfig"]
}

有关更多信息，请参见 watch-project 命令。

enforce_root_files​

自 3.1 起。

这是一个布尔选项，默认为 false。如果将其设置为 true，则只有当请求的目录包含 root_files 配置选项列出的文件之一时，watch 命令才会成功，并且只有当找到有效的项目根目录时，watch-project 命令才会成功。

如果未指定，为了帮助在版本之间过渡，watchman 将检查是否存在现已弃用的 root_restrict_files 配置设置。如果找到它，则 enforce_root_files 的有效值将设置为 true。

root_restrict_files​

从 3.1 版开始已弃用；请使用 root_files 和 enforce_root_files 来实现相同的行为。

指定一个文件列表，其中至少应存在一个文件才能使 watchman 将其添加为根目录。默认情况下，没有限制。

例如，

{
  "root_restrict_files": [".git", ".hg"]
}

仅允许在 Git 或 Mercurial 存储库的顶层进行监视。

illegal_fstypes​

指定禁止 watchman 尝试监视的文件系统类型列表。Watchman 将确定监视根目录的文件系统类型；如果类型名称存在于 illegal_fstypes 列表中，则禁止监视。您还可以将 illegal_fstypes_advice 指定为字符串，其中包含给用户的其他建议。此配置选项的主要目的是防止在网络挂载的文件系统上使用 Watchman。在 Linux 系统上，Watchman 可能无法确定已挂载文件系统的确切类型名称。如果 watchman 不知道文件系统类型，则将其报告为 unknown。

例如，

{
  "illegal_fstypes": ["nfs", "cifs", "smb"],
  "illegal_fstypes_advice": "use a local directory"
}

将阻止监视挂载在网络文件系统上的目录，并提供使用本地目录的建议。您可以省略 illegal_fstypes_advice 设置以使用默认建议将目录重定位到本地磁盘。

ignore_vcs​

将特殊的 VCS 忽略逻辑应用于命名目录集。此选项的默认值为 [".git", ".hg", ".svn"]。使用特殊的浅层逻辑观察和监视与此选项匹配的目录。浅层监视允许 watchman 适度地滥用版本控制目录来存储其查询 cookie 文件，并观察 VCS 锁定活动，而无需监视大型树的整个 VCS 数据集。

ignore_dirs​

Watchman 完全忽略匹配的目录。这对于忽略仅包含构建产品且由于文件数量庞大而不需要文件更改通知的目录很有用。

例如，

{
  "ignore_dirs": ["build"]
}

将忽略被监视树顶层的 build 目录及其下面的所有内容。它永远不会出现在树的 watchman 查询结果中。

在 Linux 系统上，ignore_dirs 在 OS 级别受到尊重；内核根本不会告诉 watchman 有关被忽略目录的更改。macOS 和 Windows 对此的支持有限或没有支持，因此 watchman 需要处理并忽略此类更改。

对于大型树或特别繁忙的构建目录，建议您将繁忙的构建目录移出树以获得更佳的性能。

自 2.9.9 版以来，如果您在 ignore_dirs 中列出了也在 ignore_vcs 中列出的目录，则 ignore_dirs 的位置将优先。这听起来可能没什么大不了的，但由于 ignore_vcs 用作放置 cookie 文件的提示，因此在早期版本中让这两个选项重叠会破坏 watchman 查询。

自 4.6 起。

在 macOS 上，可以在 OS 级别加速 ignore_dirs 中列出的前 8 个项目。这意味着甚至不会将对这些路径的更改传递给 watchman 服务。超出前 8 个的条目由 watchman 处理并忽略。如果您的工作负载容易发生重新爬网事件，您将需要优先处理 ignore_dirs 列表，以便最繁忙的忽略位置占据此列表中的前 8 个位置。

gc_age_seconds​

早于此时间段的已删除文件（和目录）会定期从文件系统的内部视图中删除。在删除它们之前，它们对查询可见，但它们的 exists 字段将设置为 false。删除后，watchman 将记住已删除节点的最新时钟值。任何基于早于上次删除时钟的时钟的 since 查询都将被视为新的实例查询。这允许客户端检测并选择如何处理他们错过更改的情况。有关更多信息，请参见本文档中的其他位置的 is_fresh_instance。此项的默认值为 43200（12 小时）。

gc_interval_seconds​

根据上面的 gc_age_seconds 选项说明，检查并删除已删除节点的频率。此项的默认值为 86400（24 小时）。将其设置为 0 可禁用定期删除操作。

fsevents_latency​

控制传递给 macOS 上的 FSEventStreamCreate 的延迟参数。该值以秒为单位测量。在 watchman 的 3.2 版之前的此参数的固定值为 0.0001 秒。从 watchman 的 3.2 版开始，默认值现在为 0.01 秒，并且可以在每个根目录下控制。

如果您观察到 kFSEventStreamEventFlagUserDropped 出现问题，增加延迟参数将允许系统将更多更改通知批量处理在一起并更有效地运行。

fsevents_try_resync​

这是 macOS 特有的。

自 4.6 起。

默认为 false。如果设置为 true，如果监视收到 kFSEventStreamEventFlagUserDropped 事件，请尝试从 fsevents 日志重新同步（如果可用）。如果一个或多个卷以只读方式挂载，如果管理员已清除该日志，或者如果 fsevents id 号已滚动，则该日志可能不可用。

此重新同步操作是有利的，因为它有效地允许从已知时间点倒回和重新播放事件流，并避免了重新爬网整个监视的需要。

如果此选项设置为 false，或者如果该日志不可用，则将使用重新爬网被监视目录树的原始策略。

自 4.7 起。

默认值已更改为 true。此外，此重新同步策略现在也应用于 kFSEventStreamEventFlagKernelDropped 事件。

自 2021 年 12 月起。

默认值已更改为 false。此设置可能存在未诊断的正确性问题。

prefer_split_fsevents_watcher​

这是 macOS 特有的。

默认为 false。如果设置为 true，Watchman 将使用多个 FSEvents 流来监视目录层次结构，而不是单个流。这已显示为显着减少了 kFSEventStreamEventFlagUserDropped 事件的数量，对于向 ignore_dirs 中列出的顶层目录发出大量写入的工作流程。

idle_reap_age_seconds​

自 3.7 起。

在成为收割候选对象之前，监视可以保持空闲的秒数，以秒为单位测量。此项的默认值为 432000（5 天）。将其设置为 0 可防止收割。

当监视在 idle_reap_age_seconds 内没有对其进行操作的命令时，该监视被认为是空闲的。如果空闲监视没有触发器也没有订阅，则将取消它，释放相关的操作系统资源，并从状态文件中删除。

hint_num_files_per_dir​

自 3.9 起。

用于预先确定哈希表的大小，这些哈希表用于跟踪每个目录中的文件。这在文件系统的初始爬取过程中影响最大。 将此值设置得太小会增加哈希插入发生冲突的几率，并增加插入和后续获取的成本。

在 Watchman 的 3.9 版本之前，此值固定为 2。 从 3.9 版本开始，默认值为 64，可以通过 .watchmanconfig 或全局 /etc/watchman.json 配置文件中的此设置进行配置。

将此值设置得非常大会增加树中每个目录的内存开销；该值向上舍入到下一个 2 的幂，并在指针数组中预先分配。在 64 位系统上，将该数字乘以 8 即可得到字节开销数（在 32 位系统上，将此数减半）。 使用不区分大小写的文件系统时，开销会加倍。

从时间复杂度的角度来看，理想的大小是最大目录中的文件数。 从空间复杂度的角度来看，理想的大小是 1；您将在初始爬取期间付出冲突的代价，并获得更优化的内存使用率。 由于 Watchman 主要用作加速器，我们建议倾向于使用更多内存并减少运行时间。

hint_num_dirs​

自 4.6 版本起

用于预先确定哈希表的大小，这些哈希表用于跟踪整个监视树中的文件总集。 此默认值为 131072。

最佳大小是大于树中目录数的 2 的幂；运行 find . -type d | wc -l 将告诉您您拥有的数量。

将此数字设置得太大可能会浪费内存。 将此数字设置得太小会导致在重建哈希表时爬取期间的延迟增加。

suppress_recrawl_warnings​

自 4.7 版本起

设置为 true 时，Watchman 不会在各种请求的响应 PDU 中生成与重新爬取相关的警告字段。 默认值为 false；目的是让您组织中的某人意识到重新爬取，并能够管理配置和工作负载。 某些站点采用替代机制来抽样并向合适的人员报告此信息，并希望禁用警告，使其不会出现在无法自行进行适当配置更改的用户面前。

eden_file_count_threshold_for_fresh_instance​

这特定于 EdenFS 监视器

当设置为非零值时，如果更改的文件数超过配置的值，Watchman 将向 since 查询/订阅返回一个全新实例。 特别是在工作副本的大量更新期间，可能会更改大量文件，从而迫使 Watchman 和 EdenFS 都获取大量元数据来回答这些查询。

仅当查询指定 empty_on_fresh_instance 选项或将此配置设置为 0 时，才会启用此行为。 默认为 10000。