OverrideAudit

OverrideAudit是一个为Sublime Text 3编写的套件，它可以帮助您检测和管理工作区中的套件覆盖，让您可以轻松查看需要覆盖的文件列表，查看覆盖提供的更改，最重要的是，当您覆盖的文件被其作者修改时，会向您提供警告，以便您确定下一步操作。

如果您是OverrideAudit的新用户，有一个入门视频可供您观看，该视频展示了套件的某些关键功能。还可以查看第2.1版中添加的新功能（入门视频中未介绍的内容）。

---

安装

套件控制

安装此套件的最佳方式是通过套件控制，因为这样可以在不进行任何操作的情况下确保套件保持最新。

要使用套件控制进行安装，请打开命令面板选择Package Control: Install Package命令并搜索OverrideAudit。

手动安装

为了手动安装套件，请将仓库克隆到Sublime Text的Packages目录。您可以通过选择菜单中的 Preferences > Browse Packages...来找到此目录。

对于大多数用户而言，不建议手动安装套件，因为在这种情况下，您需要手动维护所有内容的更新。您只有在有非常充分的理由这样做，并且足够熟悉此过程以正确执行时，才应使用手动安装。

---

使用方法

OverrideAudit提供一系列命令来帮助您发现并检查当前设置的包覆盖项，查看您的覆盖项与底层包文件的差异，最重要的是能够检测文件是否被作者更新。

除了手动执行命令外，OverrideAudit还会在每次您升级Sublime Text或包时自动检查已过期的覆盖项，以此保护您。

可以通过命令面板以及使用工具 > OverrideAudit子菜单下的选项通过菜单来执行OverrideAudit命令。此外，一些命令在打开包名或覆盖项名称的上下文菜单或在报告上时作为上下文菜单项提供。

一些命令，例如“刷新”过期的覆盖项，只能通过上下文菜单项提供，这样您可以直接针对您感兴趣的包或覆盖项。

以下列表了在命令面板中看到的可用命令；菜单项名称类似。

OverrideAudit：包报告

这将显示Sublime Text中当前已安装的所有包的列表，以表格格式显示。表格将列表的包按Sublime启动时加载的近似顺序列出。

对于每个包，都会表明该包是否为[S]ipped，[I]nstalled或[U]npacked（有关更多信息，请参阅术语表部分）。

此外，当前禁用的包将以[方括号]显示，代表已安装包的依赖项的包将以<尖括号>显示。

每个包名都支持一个上下文菜单项，允许您为该包打开批量diff报告，使您能快速了解任何覆盖项的概况。有关更多信息，请参阅OverrideAudit：批量diff单包命令。

OverrideAudit：覆盖报告

这将显示所有存在覆盖项的包的列表，无论是[简约的还是[完整的覆盖项），对于当前[过期的包或覆盖项文件，有明显的指示（有关这些术语的更多信息，请参阅术语表部分）。

对于显示的每个包，将显示与包报告中相似的简略指令，指示该包是否为[S]ipped，[I]nstalled或[U]npacked。

一个表示[完整的覆盖项的包将在输出行旁边显示相应的文字。如果这样的包已过期，会添加额外的说明。

所有包的[简约的覆盖项将显示在包名称下方报告，如果它们当前是[过期的，则可能以[X]标记为前缀，如果它们当前是[未知的，则可能以[?]为前缀。

与包报告一样，在包名称上提供上下文菜单项，以快速进行该包的覆盖项批量diff。此外，覆盖项文件名包括上下文命令，允许您快速编辑、diff或删除该覆盖项。

OverrideAudit：覆盖报告（仅过期）

此命令与标准覆盖报告命令操作相同，但其输出将仅限制在[仅包含某种形式的过期覆盖项（简约或完整）的包。

这允许您仅仅关注可能需要您更多关注的那些覆盖项。

OverrideAudit：覆盖报告（排除未更改）

此命令与标准覆盖报告命令的工作方式相同，但排除了与其底层文件内容匹配的覆盖，因此这些覆盖不会出现在报告中。这可能导致包含此类覆盖的程序包在报告中完全不显示。

这种排除不适用于二进制、未知或过期的覆盖；这些覆盖将继续出现在报告中。

OverrideAudit: 单个覆盖差异

这将在快速面板中列出至少有一个简单覆盖的所有程序包，并允许您比较基础文件和您的覆盖之间的差异，以查看两者之间的不同之处。

当文件内容不同时，在新的缓冲区中以统一差异格式显示输出，允许您检查更改。

作为快捷方式，您可以直接从任何覆盖报告或现有的批量差异报告中直接比较覆盖文件。

diff_unchanged选项允许您指定当覆盖与底层文件相同时的差异结果。

OverrideAudit: 批量差异所有程序包

这将为所有程序包的每个简单覆盖生成差异，并将其汇总到一个输出报告中，允许您一次快速概述所有覆盖。

与覆盖报告命令类似，列出的每个程序包都有一个从程序包报告中提取的指标摘要版本，指示所讨论的程序包是[S]，被压缩，[I]，被安装还是[U]，同时也会指示该程序包是否是一个完全覆盖。此外，过期完全和简单覆盖也将在批量差异报告中表示。

报告的每一部分都会逐步缩进，这样您就可以在工作时使用Sublime代码折叠来隐藏报告的某些部分。

与覆盖报告类似，每个程序包的名称和每个覆盖文件的名称都支持上下文菜单，允许您快速批量比较、打开或以独立视图比较它们。

OverrideAudit: 单个程序包批量差异

此命令与批量差异所有程序包命令操作相同，唯一的区别是，您将提示通过快速面板选择单个程序包进行差异分析，而不是对所有程序包的所有覆盖进行差异分析。

您还可以通过程序包报告、覆盖报告或批量差异报告中程序包名称的上下文菜单访问单个程序包的批量差异。

OverrideAudit: 刷新报告

此命令可在所有OverrideAudit报告视图（程序包报告、覆盖报告或批量差异）中通过命令面板、上下文菜单或主菜单使用，并允许您快速重新运行相同的报告。

当刷新报告时，OverrideAudit忽略当前reuse_views和clear_existing选项的值，并像它们都设置为true一样操作，以便用现有报告替换。

此命令还作为报告视图或其关联编辑标签中的上下文菜单条目使用，以及通过F5键，尽管您可以更改此绑定到您喜欢的键。

OverrideAudit: 切换差异/编辑视图

此命令仅在当前文件是覆盖的编辑会话或覆盖的差异时在命令面板中可用。

尽管此命令未出现在顶级工具 > OverrideAudit菜单中，但它在适当的文件视图的上下文菜单以及覆盖报告或批量差异中覆盖文件的上下文菜单中都可以看到。

此外，OverrideAudit包含一个键绑定到标准Sublime键，用于在关联文件之间切换（Windows/Linux上的Alt+O或MacOS上的⌘+Alt+向上），并在适当的文件视图中操作。

无论您如何触发命令，任何现有的针对此覆盖的编辑或差异视图都会直接切换。在差异视图的情况下，差异将被重新计算，以便任何已保存的更改可以立即反映出来。可以通过启用配置选项save_on_diff来确保在需要的情况下，首先持久化文件中的未保存更改。

此命令忽略当前值reuse_view、clear_existing和diff_unchanged设置，并且假定它们已分别设置为true、true和diff，以确保最终不会出现大量重复的视图。

在覆盖编辑视图中，可以使用mini_diff_underlying设置在缓冲区中设置差异指示符，以差异底层被覆盖的包文件而不是磁盘上显示的文件。

OverrideAudit：撤销当前覆盖

当前文件是一个非unknown覆盖编辑会话时，此命令仅在命令调色板中可用；也就是说，该文件表示存储在底层sublime-package文件中的文件。

尽管此命令未出现在顶级工具 > OverrideAudit菜单中，但它在适当的文件视图的上下文菜单以及覆盖报告或批量差异中覆盖文件的上下文菜单中都可以看到。

调用该命令时，将会确认您是否要执行撤销操作，然后将磁盘上的覆盖替换为从源sublime-package文件中新解包的副本。这样做会将该文件恢复到原始版本，而保留文件本身。

可以使用confirm_revert设置在运行命令之前禁用确认检查。

OverrideAudit：在外部打开差异

当前文件是一个覆盖差异时，此命令仅在命令调色板中可用。

尽管此命令未出现在顶级工具 > OverrideAudit菜单中，但它确实出现在覆盖差异视图的上下文菜单中。

无论您如何触发该命令，都会创建一个临时文件，该文件包含sublime-package文件中的基础文件，以便外部程序访问它。此文件作为只读文件创建，以表明对其更改将会丢失，因为OverrideAudit将在外部工具终止后删除它。

此命令需要将external_diff设置设置为告诉OverrideAudit如何打开外部差异。默认情况下，此设置设置为false，这将导致命令隐藏。

OverrideAudit：创建覆盖

此命令可以从主菜单和命令调色板中使用，通过提示您覆盖的包和资源，允许您创建新覆盖。提示将仅显示可以包含覆盖的包（即不是代表sublime-package文件的包或目前包含在ignored_packages列表中的包不合格）以及将仅显示未已覆盖的包资源。

选择资源时，将打开一个新的缓冲区，显示底层资源的内容，允许您进行所需的任何更改。覆盖只有在您保存文件时才会创建，因此您可以在任何时候（甚至是编辑后）关闭选项卡而无需担心。

首次保存缓冲区时，OverrideAudit将确保在Packages文件夹下创建正确的文件结构，并将新的覆盖放在正确的位置。

可以使用mini_diff_underlying设置设置侧边栏中的差异标记，以便与基本包文件差异，使您更容易跟踪更改。

OverrideAudit：打开资源

此命令可以从主菜单和命令调色板中使用，允许您打开任何包资源进行查看（并可能创建覆盖）。这与创建覆盖命令的工作方式类似，但在这里将显示所有包资源，任何是覆盖的将在面板中进行标注。

当选择一个资源时，该文件将被打开以供查看。如果该文件为覆写文件，则可以按照正常方式编辑该文件；常规资源将以只读方式打开，并需要您使用 覆写当前资源 命令才能使其可编辑。

覆写审计：覆写当前资源

此命令可从主菜单和命令面板中使用，条件是当前视图代表一个通过命令面板中的 Sublime Text 查看包文件 命令打开的包资源。

此命令会立即将当前缓冲区提升为潜在的新的覆写文件，就像是您使用了 覆写审计：创建覆写 命令并选择了适当的包和资源一样。与该命令一样，覆写文件不会在您首次保存时创建。

覆写审计：删除覆写

此命令仅在当前文件是覆盖的编辑会话或覆盖的差异时在命令面板中可用。

与 交换差异/覆写视图 命令一样，此命令不会出现在顶层 工具 > 覆写审计 菜单中，但会出现在适当文件视图的上下文菜单中，以及从 覆写报告 或 批量差异 中的覆写文件上下文菜单中。

此命令将在提示您确认确实想要删除此文件后删除当前覆写。覆写审计尝试使用与 Sublime Text 删除文件相同的内部机制将覆写发送到回收站。

当删除覆写时，现有编辑会话保持开放，Sublime 将指示它们有未保存的更改，因为该文件已丢失。

如果您希望能够删除覆写而不需要先提示，则可以将配置设置 confirm_delete 设置为 false。

---

自动报告已过期覆写

虽然包覆写对您自定义 Sublime Text 至您的喜好至关重要，但 Sublime 在您覆写上次创建覆写以来已更改的文件时不会警告您。

在这种情况下，更新的源文件被忽略，并保留您的覆写文件，这意味着任何原始包作者所做的错误修复或改进将不会对您可见，并且您永远不会知道。

为了防止这种情况发生而不让您意识到，覆写审计将在检测到有更新后自动尝试生成报告，告诉您是否有任何已过期的覆写。

生成的报告是一个 覆写报告，其中只包含关于过期的覆写的信息。只有当存在已过期的覆写时，报告才会显示，这样覆写审计就可以在没有任何潜在问题时避免打扰您。

将在以下情况下生成自动报告：

• 每次启动 Sublime Text 时，如果版本号与上次运行时不同，表示您已将 Sublime Text 升级到不同的版本。
• 每次从您首选项文件中的 ignored_packages 列表中删除包。例如，每次 Package Control 升级包时都会这样做。

---

更新过期覆写

检测到过期覆写时，检查源文件与您的覆写之间的更改是个好主意，这样您可以确定是否需要将更改合并到您的覆写中，或者如果不再需要它，则可能完全删除它。

由于 PackageControl 更新包的方式，覆写审计可能报告覆写为已过期，而原始文件实际上没有进行任何内容更改。

在这些情况下，为了阻止文件被报告为过期，其磁盘上的时间戳需要被更改，使其比新的软件包文件更近。如果您正在打开覆盖以查看其内容，这就像简单地重新保存文件一样简单。

如果您有许多覆盖，无论是单个软件包中的还是分布在多个软件包中，一个好的选择可能是批量差异操作之一，这允许您快速扫描和查看更改，仅编辑需要特殊关注的文件。

在这种情况下，打开和保存文件会很快成为一种麻烦。因此，OverrideAudit可以在上下文菜单中提供一个刷新命令，一次性刷新单个覆盖或软件包中的所有覆盖。

默认情况下，在命令执行之前会提示您是否要进行此操作。您可以通过修改confirm_freshen配置选项来阻止这种情况发生（如果需要的话）。

刷新操作将文件的最后修改时间更新为当前日期，这样OverrideAudit就知道一切都是最新的。

---

注意：如果您在未将其添加到ignored_packages列表或Sublime没有运行的情况下手动升级软件包，OverrideAudit将无法检测到任何更改，并且不会自动为您生成报告。

因此，在手动升级软件包的过程中，从命令面板手动运行此报告可能是一个好主意。

---

配置

以下配置选项可用于OverrideAudit。您可以在偏好设置 > 软件包设置 > OverrideAudit菜单项下或通过命令面板使用偏好设置: OverrideAudit 设置查看默认设置以及您自己的自定义设置。在MacOS中，偏好设置菜单位于Sublime Text菜单下。

reuse_views: true/false （默认：true）

OverrideAudit通常创建一个输出视图来显示操作的成果。当此选项启用（默认）时，OA将尝试找到上次创建的视图并为其新命令重用它。如果禁用，每次都创建新视图。

一些OverrideAudit命令可能忽略此设置。

clear_existing: true/false （默认：true）

当reuse_views启用（默认）时，此选项控制在执行命令之前是否需要清除重用视图的已存在内容，或者将新的输出追加到现有视图的末尾。

一些OverrideAudit命令可能忽略此设置。

ignore_overrides_in: Array （默认：[]）

这是一个可选的软件包名称列表，不应将其包含在显示/计算覆盖信息的命令中。此选项的格式与ignored_packages Sublime设置相同。

这不会影响显示在一般软件包列表中的软件包；它仅隐藏出现在显示存在覆盖的软件包列表中的软件包，例如覆盖报告或查找和差异覆盖的命令。

注意：您在此列表中的软件包中创建的任何覆盖都将对您隐藏，因此请非常小心地添加到列表中。

diff_unchanged: String （默认：“diff”）

当使用Diff 单个覆盖命令时，此设置控制当所选覆盖与底层文件没有差异时，会发生什么。

此设置的可能的值是

• "diff" 在空差异标签中打开一个标签
• "ignore" 忽略命令；状态行将指出缺少更改
• "open" 打开文件以进行编辑，允许您查看其内容或进行新的修改。

diff_context_lines: Number （默认：3）

当显示覆盖的差异时，此选项指定要显示多少不变的行在每个差异前后的，以提供更好的背景信息。

diff_empty_hdr: Boolean （默认：false）

启用时，即使没有要显示的更改，也能显示参与比较的文件的源文件和相关的时间戳。

此设置既适用于批量比较，也适用于单个文件的比较。但请注意，对于单个文件的比较，如果将 diff_unchanged 设置为 "diff"，此选项才会生效，否则不会显示比较。

save_on_diff: 真伪 (默认: 假)

此设置控制 OverrideAudit 在从重写编辑切换到重写差异时，是否确保将在磁盘上持久保存任何未保存的更改，以便您的更改会反映在比较中。

对于代表不再存在于磁盘上的文件（即，您打开了重写并随后删除它）的带有未保存更改的缓冲区，此选项没有作用，以确保您不会在保存它时意外恢复已删除的文件。

mini_diff_underlying: 真伪 (默认: 真)

此设置控制 Sublime Text 的 mini_diff 功能如何在您编辑重写时与之交互（包括它们通过 创建重写 命令最初创建时）。

启用时，在编辑重写时，Sublime 用于在侧边栏计算差异指示符的文件将设置为正在工作的重写的解包版本。

这使得您可以使用内部 Sublime 功能在不同更改之间跳转，以轻松导航重写，包括显示每个更改的行内差异块，并允许您撤销更改。

此设置需要将您的 Preferences.sublime-settings 文件中的 mini_diff 设置为 真；当设置为 假 或 "auto" 时，mini_diff_underlying 设置无效果。

confirm_deletion : 真伪 (默认: 真)

当删除文件时，此设置控制 OverrideAudit 在删除发生之前是否提示您确认删除。

OverrideAudit 使用与 Sublime Text 同船随带的 send2trash 库来执行文件删除。

confirm_freshen : 真伪 (默认: 真)

当刷新已过期的重写文件时，此设置控制 OverrideAudit 是否在操作发生之前提示您确认操作。

尽管此操作不具有破坏性，刷新过期的重写将阻止 OverrideAudit 提醒您它已过期。

confirm_revert : 真伪 (默认: 真)

当撤销重写文件时，此设置控制 OverrideAudit 是否在操作发生之前提示您确认操作。

binary_file_patterns: 数组 (默认: 来自用户设置)

此设置与同名的 Sublime Text 设置相同，控制哪些文件被认为是在执行差异操作的二进制文件。

此操作的默认值取自您的常规 Sublime Text 用户设置，因此您仅在需要将不同集的文件视为差异操作的二进制文件时，才需要在 OverrideAudit 设置中指定值。

report_on_unignore: 布尔 (默认: 真)

OverrideAudit 可以自动生成报告来检查每次从您的 Preferences.sublime-settings 文件中的 ignored_packages 列表删除包时的 过期 重写。

当您手动决定重新启用已忽略的包时，此情况也会发生，这表明 Package Control 已完成包的升级。

启用时，只有找到过期的重写时才会显示报告。

external_diff: 对象、字符串或假 (默认: 假)

此设置可以是 假（默认值）、字符串 "sublimerge" 或 JSON 对象。

值设置为false将禁用外部diff功能，而字符串"sublimerge"指示OverrideAudit使用Sublimerge Pro或Sublimerge 3来进行diff。这要求安装并启用其中之一，否则假定值为false。

当设置为JSON对象时，对象可能包含shell_cmd、working_dir和env等键名，它们的职能与Sublime构建系统相同。此外，linux、windows和osx键名可以设置为针对特定平台的JSON对象。

除了所有标准的构建变量外，变量$override和$base分别展开为覆盖文件和基础文件的文件名，用于命令行。

ignore_unknown_overrides：数组或布尔型（默认：VCS目录）

此设置控制是否在覆盖或批量diff报表中显示未知覆盖，也可以控制显示和掩藏哪些未知覆盖。

值为true表示在报告中永远不应显示任何未知覆盖；这就是在引入此设置之前OverrideAudit的行为。

值为false表示应显示每个包中的每个未知覆盖。

此设置还可以设置为正则表达式数组；在这种情况下，值既类似于true又类似于false；除非它们匹配数组中的正则表达式之一，否则未知覆盖将会显示。

列表中的正则表达式匹配时，就好像存在隐式的行起始锚点（^）并且区分大小写，或者基于底层操作系统的文件系统不区分大小写。

此设置的默认值是一个模式列表，可以隐藏所有存储在git、subversion或mercurial控制目录中的文件。

注意：包资源始终使用posix路径分隔符（字符/）表示。

---

术语

以下术语在文档中使用，这里对不熟悉如何在Sublime Text 3中使用和引用包的用户进行说明。

打包包

一个打包的包是包含在sublime-package文件中的包。实际上，这是一个扩展名不同的zip文件。包文件的名称提供了包自身的名称。

这是一个方便安装包的方法，因为所有构成包的文件和资源都包含在单个文件中。

包文件Python.sublime-package是一个打包包，提供了Python包的内容，该包为在Sublime Text中编写Python程序提供了支持。

未打包包

一个未打包的包是存储在Sublime Text Packages目录子目录中的包，可以通过从菜单中选择Preferences > Browse Packages...在Sublime中访问。包的名称来自存储包的目录名称。

Packages\User目录的内容被认为是名为User的包的内容。

随附包

一个随附的包是随Sublime Text本身一起提供的打包的包。这些包提供了Sublime Text的核心功能，并存储在与Sublime可执行文件在一起的特定位置。这使得它们在相同计算机上的所有Sublime用户中都是通用的。

随附包Default.sublime-package提供了其他包修改的一组默认键绑定、设置、菜单项等。

已安装包

安装包是一种打包的包，它存储在安装包目录中，该目录位于用于存储未打包的包的 Packages目录之上。

请注意，这并不意味着未打包的包在某种意义上没有被安装；这个术语纯粹是用来区分以特定格式和位置安装的包。

Package Control作为安装包安装，并且它安装的许多包也都是这样安装的。

覆盖

覆盖是文件或文件，它覆盖了包中包含的同名文件。当覆盖有效时，Sublime将忽略原始打包版本的文件，并使用覆盖文件代替。

这可以用来根据您的喜好修改包的行为，但也很危险，因为如果文件被包作者修改，覆盖将继续掩盖这些更改和改进。

检测这种情况是OverrideAudit的核心功能之一。

简单覆盖

简单覆盖是最常见的覆盖类型，其中包被部分解压然后修改。这意味着在Sublime的Packages目录中有一个名为现有发货或已安装包的目录，它包含与sublime-package文件中相同的同名文件。

文件Packages\Python\Python.sublime-build是一个简单的覆盖，导致Sublime忽略来自Python包的发货版本，允许您修改Python的构建方式。

完整覆盖

完整覆盖比简单覆盖更少见。这种情况发生在与发货包同名的打包包被安装到安装包文件夹中时。当这种情况发生时，Sublime将忽略发货版本的包，而使用另一个版本，就像它是与Sublime一起发货的包一样。

文件Installed Packages\Python.sublime-package是已发货的Python包的完整覆盖。对Sublime来说，这是提供此类语言所有功能的Python包。

过期的覆盖

这个术语仅属于OverrideAudit，用于表示覆盖（无论是简单还是完整）正在覆盖在源处已经更新的文件（例如，通过Sublime text的升级或包作者对其的修改）。

当这种情况发生时，Sublime不会自己警告您，将继续使用您的覆盖，可能会错过重要的错误修复或新功能。

OverrideAudit中的工具旨在帮助警告您这种情况的发生，并允许您轻松查看已更改的内容，这样您可以决定如何最好地处理这种情况。

未知覆盖

这个术语仅属于OverrideAudit，用于表示解压的包文件夹包含源sublime-package文件中不存在的文件。

这样的文件在技术上不是覆盖（因为它们没有覆盖任何东西），但OverrideAudit将在批量diff和覆盖报告中显示它们，以提醒您解压缩包中存在额外的未知文件。可以使用ignore_unknown_overrides设置来调整未知覆盖的显示。

---

许可协议

版权所有 2017-2019 Terence Martin

任何人有权免费获得本软件及其相关文档文件（以下简称“软件”）的副本，并有权不受限制地处理该软件，包括但不限于使用、复制、修改、合并、发布、分发、分包和/或销售软件的副本，并授权向提供软件的人员这样做，但应符合以下条件：

上述版权声明和本许可声明应包含在软件的任何副本或主要部分中。

软件按“现状”提供，不包括任何明示或暗示的担保，包括但不限于 merchantability、适合特定用途和 non-infringement 的担保。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任承担责任，不论是由于合同、侵权或其他原因，不论是否由软件、软件的使用或其他情 况产生。