Quick Start

Last updated: Oct 18th, 2017

Introduction

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.

Requirements

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 3092 or higher; no other external software or packages are required.

Installation

Package Control

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.

Note:

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.

Manual Installation

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.

Warning:

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.

First Steps

After Installation

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.

Warning:

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.

Package Report

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.

Package Report Sample

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.

Override Report

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.

Override Report Sample

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 (here, there is a single override of the exec.py plugin in the Default package).

As in that report, you can 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.

Override Diff Sample

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.

Next Steps

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.