At its core, OverrideAudit helps automate the actions you would normally take to allow you to keep track of and work with your overrides more easily. Although what it can do is easy to understand, you may find yourself wondering how or why you would actually use it in the real world.
This page outlines some of the tasks that you might carry out with OverrideAudit and what your workflow might be while performing those tasks.
OverrideAudit strives to integrate with your normal Sublime workflow as much as possible, unobtrusively sitting in the background waiting for you to call on its services. In order to stay out of the way, many of the commands and tasks available are context sensitive in nature, appearing only in the situations where they are needed.
Commands for creating Reports are always available from within the Command Palette or the Main Menu. Additional commands become available in the Command Palette as well as the context menu of views that pertain to overrides (reports, while editing an override, etc) as needed.
In most places, the context menu is specific not only to the editor pane you are using, but also to the location within the pane that you open the menu. For example, package names in Reports have a different set of context sensitive items than the names of overrides do.
Most of the ways into the OverrideAudit workflow are by first generating a report of some kind in order to gather information about how best to proceed. In most cases that will be an automatically generated report that informs you of potential problems.
Reports tell you things such as what packages you have installed as well as the overrides that exist inside of them. From these reports, you can use the available context sensitive commands to get at the information you need to keep Sublime running in tip top shape.
For most users, working with overrides starts with an automatically generated Override Report, which may happen after an update to Sublime or one of the packages you have installed. In these cases, OverrideAudit may detect that one or more of your overrides has expired and may require attention.
This report allows you to get a quick overview of all of the overrides you currently have and which ones may require your attention to ensure that you don't miss out on anything important.
OverrideAudit can also generate various Reports on demand, including the expired override report that it automatically generates when needed. These reports can be created either in response to an automatic report to help diagnose potential problems as well as to gain insight into your overrides at any time.
Although the various reports help you to see what overrides you have and their state, their main focus is in helping you to work with your overrides in general. The reports help you focus in on the overrides that may need your attention the most.
OverrideAudit adds extra context sensitive functionality to open override files, allowing you to see how they're different from the files they are overriding, update them when they need changes, and even to remove them when you're done with them.
Before you can start working with your overrides, you need to know that they exist in the first place. The easiest way to do that is via an Override Report. This report will show you what overrides exist in each package (if any), as well as providing an indication as to whether that override is expired or not.
Another option is the Bulk Diff Report, which contains the same information as the Override Report and also includes a unified diff for each override so that you can immediately see how each override is different from it's underlying file. This report can be generated either for all packages all at once or for just a single package, depending on your needs.
When working with OverrideAudit, you may determine that you would like to make changes
to an override that already exists. From any report which is showing you the name of
an override, you can open the context menu over an override and select the
OverrideAudit: Edit Override command to automatically open the override
for editing.
If you have a diff view open for an override, you can open the context menu anywhere
within the file contents or it's editor tab and select the OverrideAudit: Edit this Override
command, select the OverrideAudit: Swap Diff/Edit View command from the
Command Palette or use the Alt+O or Cmd+Alt+Up keyboard shortcut to
immediately swap to an edit view for that override.
It is also possible to open an override manually using the standard Sublime file operations or via another package such as PackageResourceViewer. Regardless of how you open an override, OverrideAudit will detect that it is an override and seamlessly integrate with it.
Once you know you have an override, you often need to know exactly how your override is different from the underlying file that it is overriding. For this purpose, OverrideAudit provides the ability to calculate and display a diff of an override, allowing you to easily see how things are different.
There are a variety of ways to generate a diff for an existing override, allowing you to quickly get at the information you need with a minimum of effort.
Selecting OverideAudit: Diff Single Override from the Command Palette
or Tools > OverrideAudit > Diff Single Override from the menu
will prompt you for an override and then show you a diff of it.
This command automatically filters the list of packages and the contents of the selected package so that you only see relevant information.
From within any report which is showing you the name of an override, you can open
the context menu over an override and select the OverrideAudit: Diff Override
command to open a diff for that override.
While you are editing an override you can open the context menu anywhere within
the file or it's editor tab and select the OverrideAudit: Diff this Override
command to immediately open a diff.
This operation is also available as OverrideAudit: Swap Diff/Edit View
in the Command Palette or using the Alt+O or Cmd+Alt_Up
keyboard shortcut.
For more extensive override changes, or when you have a preference to view a diff in
a favorite tool, OverrideAudit can be configured to use that tool via the
external_diff setting. This enables the
OverrideAudit: Open Diff Externally command in the context menu
and command palette while you are viewing a diff.
The mini_diff_underlying setting can be used to have OverrideAudit set up the Sublime Text incremental diff functionality to show file differences based on the unpacked version of the file.
With this option enabled (it is turned on by default), while editing overrides you can use the native Sublime Text diff navigation and display to see exactly how your override is different from the underlying file.
OverrideAudit will warn you when you have any overrides that have expired; that is, the file that it is overriding has been updated since you created or last edited your override. In such a case, you should check to see how the changes impact you and if you need to take any action (for example, to pick up new bug fixes).
OverrideAudit determines that an override has expired when the underlying file has a newer modification date than the override itself, which indicates that the source file has been potentially altered. Making any changes to an override (or just saving it without making any changes) will update the last modification time and "freshen" the override.
If you are viewing a Report that displays the names of existing overrides, you can also take the following actions:
Open the context menu on the name of an expired override and select the
OverrideAudit: Freshen Override command to freshen that single
override.
Open the context menu on the name of a package which contains at least one
expired override and select the OverrideAudit: Freshen Package
command to freshen all expired overrides within that package all at once.
Sometimes overrides reach a point where they are no longer useful. This can be because you have decided that you don't like the change, or possibly the package author has officially fixed a problem that you were working around. OverrideAudit allows you to easily delete an override when you no longer need it.
Like most commands, this operation available in a variety of ways:
From within an Edit or Diff of an override, you can select the OverrideAudit: Delete this Override
command from the context menu or OverrideAudit: Delete Current Override
from the Command Palette.
From within a report that displays the names of overrides, you can open the
context menu over the name of an override and select the OverrideAudit: Delete Override
command.
When OverrideAudit deletes an override, it tries to places it into the Recycle Bin/Trash (depending on your operating system) so that you can get it back if you need to.
This is done through the same mechanism that Sublime itself uses to delete files.
When you delete an override, Sublime will unload it but will not automatically reload the package to pick up the original file.
For this reason, it is a good idea to restart Sublime after deleting overrides to ensure that everything works as you expect it to.