A common practice in Sublime Text is the creation of a package override; a file that is used to modify the behavior of an existing package to work the way that you want it to work. Overrides allow you to easily "patch" a package to your liking without having to modify the contents of the package itself. Power users use overrides for a variety of reasons, and even newer Sublime Text users sometimes create overrides without being aware that they're doing it.
While powerful, overrides do have a drawback that can often catch you unaware. When an override is present, Sublime Text uses it unconditionally, ignoring the original package file completely. If the author of the package updates it, you're not told. This could make you miss out on important new features or bug fixes.
OverrideAudit was designed to help protect you from these problems. Behind the scenes, a check is done every time Sublime or one of your packages is updated. With OverrideAudit you can take a hands on approach to working with your overrides, or just let the automated checks help keep you abreast of potential problems.
Whether you are a Sublime Text power user with a ton of overrides or even just a casual user who wants the peace of mind of knowing that you're not missing out on any package changes, OverrideAudit has you covered.
OverrideAudit supports both the 32-bit and 64-bit versions of Sublime Text on Windows, MacOS and Linux. The only requirement is Sublime Text 3 with a build number of 3197 or higher (Sublime Text 3.2+); no other external software or packages are required.
Version 1.x of OverrideAudit supports builds of Sublime Text 3 prior to build 3197, though this version is no longer actively supported. Package Control will automatically install this version if you're using an older build of Sublime Text, but upgrading to the latest version is recommended.
The fastest and easiest way to install OverrideAudit is via Package Control, the de-facto package manager for Sublime Text. Package Control not only installs your packages for you, it also ensures that they are kept up to date to make sure that you always have the benefit of the latest bug fixes and features for all of your installed packages.
To install OverrideAudit using this method, open the command palette in Sublime
(Shift+Ctrl+P on Windows/Linux or Shift+⌘+P on MacOS) and
select the Package Control: Install Package command, then select
OverrideAudit from the list of packages.
If you are new to Sublime Text and don't have Package Control installed yet, you'll have
to do that first. More recent builds of Sublime Text 3 have an option in the
Tools menu named Install Package Control... that will install
Package Control for you, while older versions require you to follow the installation
instructions here.
Although only newer builds of Sublime Text 3 include a menu option to install Package Control, it is hidden if package control is already installed.
If you're unable to use Package Control to install OverrideAudit, it's also possible to
perform a manual installation by cloning the package source from its
GitHub repository
into your local Packages directory, which you can locate by selecting the
Browse Packages command from the command palette or from the
Preferences menu.
This method of installation is more complicated and requires that you have a knowledge
of git and how to use it in order to install the package.
If you install OverrideAudit manually, it will be up to you to ensure that you check for and install any upgrades that may exist to ensure that your version of the package is up to date.
For this reason, it is highly recommended that you not install manually unless you have a compelling reason or need to do so.
The first thing that OverrideAudit does when it is installed is perform a background scan to see if you have any expired overrides that you might need to worry about. A similar check is done every time Sublime Text is updated and when Package Control updates or installs a package.
If any expired overrides are found, a report will be created to tell you what they are so that you can take the appropriate action. This might involve making changes to your override, deleting it or just indicating that it is OK as it is.
For many users, these automated checks and the tools that OverrideAudit provides to help you deal with them may be all that you need.
OverrideAudit does not perform an automatic search for any package upgrades you perform manually or while Sublime Text is not running. In these cases, you may want to run the check manually. See the Report Page for more information.
To get your feet wet with OverrideAudit and what it can do for you, try creating a Package Report. This report will give you information on all of the packages that are currently available to Sublime Text, with extra information for how they are installed.
Select the Package Report command from the command palette or from the
menu in Tools > OverrideAudit to bring up the report in a new tab.
This report shows you a list of all packages known to Sublime, along with an indicator
that tells you whether it contains files that [S]hip with sublime, were
[I]installed as a sublime-package file, or have [U]npacked
files.
The report shows all of the packages in roughly the order that Sublime loads them at startup. This can help you diagnose potential conflicts among packages that provide similar functionality (e.g. key bindings). The report also indicates via markup any package that is in your list of ignored packages or is a dependency package used by one of your installed packages.
OverrideAudit has many context sensitive commands available via the context menu displayed when you Right click on text (on MacOS with a single button mouse, this is a Control+Click instead). Here in the Package report, try it on one of the displayed package names as well as in the report body in general to see what happens.
In addition, hovering the mouse over a package name in a report will display a popup that gives you more information about that package, including its version number, description, the dependency libraries it depends on (if any) and more.
Another useful report type in OverrideAudit is the Override Report, which lets you know on a package by package basis what overrides you currently have defined.
There are two versions of this report; one of them shows all overrides that exist, while the other shows you only expired overrides. This allows you to focus on only those overrides that may need your immediate attention. This type of report is what OverrideAudit generates for you automatically when an upgrade operation occurs that causes some overrides to be out of date.
Create a report of this type by using the Override Report command as you
did for the previous report.
This report will show you all current overrides, separated out by the package that they
are defined in. Each package that is displayed shows a shortened list of the same
markers used in the Package Report to indicate what kind of files this
package contains.
As in that report, you can hover the mouse on the package name to see more information on that package or use context menu items on the names of packages and in the report body itself to take various actions. There are also context menu operations on the names of any listed overrides.
If your report shows any overrides, try selecting the diff context menu
item for one of them, to see how your file is different from the one that is a part of
the package.
From the context menu in an override diff, you can easily open your override for editing or delete it entirely. As you might expect, from a window showing you the contents of the override, context menu items are available to allow you switch to the diff as well.
If you have a preferred external tool for performing diffs between files, you can use the external_diff setting to tell OverrideAudit about it. In this case, the content menu in the diff will also contain an option to open that diff in the configured external tool.
Using the mini_diff_underlying setting, while editing an override the diff indications in the Sublime Text gutter can be used to see diffs inline as well, without having to open dedicated diff view.
That's it for the basics of OverrideAudit! Hopefully this gives you a sense of the functionality that the package provides to help you keep track of and manage your overrides.
For more information what what an override is and how you would create one, there is a complete explanation of overrides and how they work in Sublime Text.
For more in depth information on how OverrideAudit can help you keep Sublime operating in tip-top shape, you can check out the OverrideAudit workflow and report reference to learn how to keep track of your overrides.
The command list outlines all of the various commands in OverrideAudit. You may also be interested in the various options available to help you configure OverrideAudit to work in the way that's best for you and your work flow.
