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
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
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
into your local
Packages directory, which you can locate by selecting the
Browse Packages command from the command palette or from the
This method of installation is more complicated and requires that you have a knowledge
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
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.
Package Report command from the command palette or from the
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
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
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
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
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
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
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
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.