Columns and badges

A plugin column appears in the list view's column chooser under the plugin's name, sorts like a built-in column, and can draw a badge on the item's icon in every view.

Declaring a column

"columns": [
  { "id": "photos.taken", "title": "Taken", "type": "date", "defaultVisible": false },
  { "id": "gitstatus.state", "title": "Git", "width": 56, "badge": true,
    "refreshWhenChanged": [".git/index"] }
]

width: 20 to 1000 points, default 80.
type (host API 1.2): how values are shown and sorted. text (the default) takes strings, numbers shown as text, and badges. number takes numbers, right-aligned, sorted numerically. size takes a number of bytes, formatted like the Size column. date takes an ISO 8601 string such as "2026-10-15T12:00:00Z" or "2026-10-15", shown in the user's date format and sorted by time. badge takes {symbol, color} only. A value of another type becomes an empty cell and a line in the log.
badge: true: a {symbol, color} value is also drawn on the item's icon. symbol is an SF Symbols name; color is red, orange, yellow, green, blue, purple or gray. Both names are at most 64 characters.
defaultVisible: false (1.2): the column starts hidden until the user turns it on. A hidden column is never asked for values, so it costs the plugin nothing.

Providing values

A JavaScript plugin registers ocelot.provideColumn(id, provider); a process plugin answers columnValues. Either way the plugin gets the paths of one folder in one call and returns an object from path to value:

ocelot.provideColumn("gitstatus.state", function (paths, ctx) {
  var out = {};
  paths.forEach(function (path) { out[path] = marks[path] ? BADGES[marks[path]] : null; });
  return out;
});

A value is a string, a number, {symbol, color} or null for an empty cell. Text is cut at 1 024 characters. The app reads the result one level deep and only for the paths it asked about; other keys and anything nested below a value are ignored.

The rules of a provider:

One call per folder load, with up to 2 000 paths; past that the column shows "…". Do one git status for the folder, never one per file.
Two seconds for the whole batch. A tool spawned inside a provider gets three quarters of what is left. A timeout empties the cells and counts as a strike.
No side effects. notify, openURL, openInApp and invalidateColumn throw from a provider, and a process plugin's notify outside an execute is dropped. Providers run on every folder load without the user asking.
Inside archives, columns are not requested.

Caching and invalidation

The app caches each value by the file's path, its modification date and the column. The folder's own watcher drops the folder's entries when files come and go. A value that depends on something else, such as the git index after git add, stays stale until the file itself changes. Two ways to fix that:

refreshWhenChanged (1.7) names files whose change makes the column's values stale. Each entry is a relative path (no .., no leading / or ~, up to 256 characters; at most 4 per column) looked up in the shown folder and then in each ancestor, up to 32 levels, the way git finds its repository. The app watches the found file's folder itself, folds a burst of changes into one, drops the column's cached values and asks again. The plugin is not called for it. Network volumes are never looked up or watched; at most 16 folders are watched at a time, least recently used first out. An invalid entry makes the manifest incompatible.

ocelot.invalidateColumn(id, paths) (1.6; for process plugins the invalidateColumn {column, paths} notification) drops the plugin's cached values for those paths, or for every path when paths is omitted, and the panes re-ask for the rows on screen. Only the plugin's own columns can be invalidated; at most 10 calls a second and 2 000 paths per call; never from a provider, which would loop. The Git Status demo offers a "Refresh Git Status" command that does exactly this.

A folder sorted by a plugin column keeps that order after a reload.