OverrideAudit: Official Documentation

Introduction

OverrideAudit contains several reports that help you to get a handle on what packages you currently have installed, how they're installed and what overrides they may contain. Many workflows in OverrideAudit start from a report.

All reports are always available from the Tools > OverrideAudit menu as well as from the command palette, regardless of the context of the current action you may be taking in Sublime. Additionally, Bulk Diff Reports are also available as context menu options by opening the menu over a package name in any report.

All reports share some common functionality:

The report header tells you the date and time that the report was created, so you can tell if the information is still relevant to you or not
The contents of the report can be refreshed to bring them up to date if things are changing in the background or since the report was first created
Package names are displayed in the Symbol List, allowing you to quickly jump to a package by name
Package and override names (in reports that contain them) support a context menu that provides commands that apply to that package or override

Package Report

The Package Report provides you with a complete list of all packages that you currently have installed in Sublime Text, along with extra information about them such as:

Whether it is a package that ships with Sublime or was installed by you (and if so, how)
Which packages are ignored by Sublime and which are dependencies of installed packages
The relative package load order of your packages

Creating a Package Report

Create a Package Report by selecting the Tools > OverrideAudit > Package Report menu item or by selecting OverrideAudit: Package Report from the command palette.

The result of this is a tabular report listing all of your installed packages and their attributes.

Package Report (Header portion)

Package Report (Showing dependencies)

Report Contents

The Package Report consists of a table that lists all of the packages you currently have installed for Sublime Text, along with a header that serves as both a legend to tell you what the symbols in the report mean and as a count for all packages you have installed.

Package names in the report have names reported in three different ways, conveying extra information about that package:

Packages in [Square Brackets] are currently being ignored by Sublime Text because you have placed them in the ignored_packages list, such as the Vintage and TypeScript packages in the screen shot above.
Packages in <Angle Brackets> are dependency packages that are providing support for packages you have installed, such as dateutils in the screen shot above
All other packages are just normal Sublime Text packages

Packages themselves can be represented in any or all of the following states:

[S] if this is a package that ships with Sublime Text by default
[I] if this is a package that you installed as a sublime-package file
[U] if this package contains unpacked files in the Packages folder.

In order to contain an override, a package must both contain [U]npacked files as well as being installed as a sublime-package file (that is, either [S]hipped with Sublime or [I]nstalled by you). This documentation contains a terminology guide if you are unfamiliar with these terms as well as a page on overrides if you are unclear on what they are or how you would create one.

The packages in the table are listed in roughly the order that Sublime loads them when it starts (see Merging and Order of Precedence in the Sublime Text Community Documentation for full details).

Hovering the mouse over the name of a package in a package report (or in any report) will show a hover popup with more information about the package, such as it's version and description, among other details.

Override Report

The Override Report is the main reason for using OverrideAudit. With it you can get a quick overview of all of the package overrides you currently have, sorted out by the package that they are contained in.

There are two versions of this report, one which shows you all overrides that exist and another that shows you only those overrides which have expired. This second version is the report that will automatically get generated in certain circumstances. See below for more information.

Creating an Override Report

Create an Override Report by selecting the Tools > OverrideAudit > Override Report menu item or by selecting OverrideAudit: Override Report from the command palette.

There are two versions of this command, allowing you to create either an Override Report that shows all overrides that exist (the default) or a version that shows you only those overrides which have expired.

Override Report (All overrides)

Override Report (Expired overrides only)

Report Contents

The Override Report consists of a list of packages which contain overrides. Each package in the report is followed by a list of all of the simple overrides that currently exist for that package, if any.

Packages in this report are marked up similarly to how they appear in the Package Report; they contain a compressed version of the package state headers ([S],[I], [U]) and their names may be wrapped in square or angle brackets to denote their status of being ignored or dependencies.

In addition, packages which are complete overrides are also marked with additional text to indicate this to you. This is a reminder and displayed for any package which is both [S]hipped and [I]nstalled at the same time. The JavaScript oacjage in the above screen shots are an example of such a package.

Any items which are expired are marked with additional text to call attention to this fact. Expired overrides are prefixed with a marker to indicate that they are e[X]pired, while an expired complete override has its package name suffixed with the text [EXPIRED]. In the images above, the complete override on the JavaScript package and the HTML.sublime-syntax override file are examples of expired overrides.

When the ignore_unknown_overrides setting is turned on (it is enabled by default) the Override report will also show unknown overrides in the report prefixed with a [?] marker to call your attention to such files.

The Expired Only version of this report, as its name suggests, shows only those packages that contain expired overrides. This allows you to focus your attention on only those overrides whose original files may have been modified in a way that makes your override invalid.

Note:

An Expired Only Override Report is created automatically by OverrideAudit whenever Sublime Text starts and the version number is different than it was on the last run (i.e. Sublime has been updated).

Additionally, the report_on_unigore setting (which defaults to true) also causes this report to be generated in cases where a package is removed from the list of ignored packages, such as when it has just been upgraded.

In both cases, the report will not appear unless there is actually at least one expired override to report, so as not to get in your way.

Note:

The Expired Only version of the report does not display unknown overrides; these only appear in the normal override report. This is because such files may be in place intentionally with no ill effect, so automatically generated versions of the report would become a nuisance.

Since it is possible that such a file may represent an override that is no longer valid, you may want to check this manually from time to time.

Bulk Diff Report

OverrideAudit allows you to easily create diff of a single override in order to determine how you've changed the underlying file. In some cases you may have multiple overrides at once for a package, such as when you are working on modifications to an existing package.

For such cases, OverrideAudit allows you to create a Bulk Diff Report, which will diff all of the overrides for a package or packages all at once. This allows you to easily get a birds eye view of how your package is different from the underlying version.

Creating a Bulk Diff Report

Create a Bulk Diff report by selecting the Tools > Override Audit > Bulk Diff menu item or via the Override Audit: Bulk Diff from the command palette. You may also obtain a bulk diff of any package by selecting the command from the context menu on any package name in any report.

There are two versions of this command, allowing you to create either a bulk diff of all packages that contain overrides or only for a single package depending on your needs.

When creating a bulk diff from a single package, a quick panel will be displayed to allow you to select the package to diff. This panel will display only those packages that currently contain overrides.

Note:

Although OverrideAudit will tell you when a package has a complete override in place, it does not currently support creating a diff between your override package and the shipped package.

This is due to the possibility that a complete override may have an entirely different file set than the original package, making a one to one file comparison impossible.

Note however that you may still create a bulk diff report for simple overrides contained within a complete override, if any should exist.

Bulk Diff Report (All packages)

Bulk Diff Report (Single package)

Bulk Diff Report (No overrides)

Report Contents

A Bulk Diff Report is visually similar to an Override Report; it contains a list of all packages it has been told to diff (all packages with overrides or just a single package) along with a list of all simple overrides contained in those packages, if any.

Where an Override Report only indicates that an override exists, a Bulk Diff report shows you a diff of that particular override against the version of the file that it is overriding, allowing you to see what's different.

When the ignore_unknown_overrides setting is turned on (it is enabled by default) a Bulk Diff report will also show unknown overrides in the report prefixed with a [?] marker to call your attention to such files. These files will not contain any diff information (there's nothing to diff against) but this provides a reminder to you that they exist, since other overridden resources may or may not make reference to them.

The report uses a set level of indentation to allow code folding to quickly fold away any overrides or packages that you see fit. This allows you to for example fold away packages and overrides as you have looked at them, or to systematically work your way through the report with a minimum of visual clutter.