Library
Menu

Custom Format Definitions

BetterZip 6 lets you add custom archive formats using external CLI tools. Instead of being baked into the app, each format is described by a JSON file that tells BetterZip how to detect, list, extract, compress, and test it. You can edit the bundled definitions to expose extra options or add new formats yourself.

What you can do with this

  • Add support for a niche archive format that has a Mac command-line tool but no native BetterZip handler.
  • Customize options of a built-in tool that BetterZip’s standard settings don’t include (e.g., a compression level you want available in the save panel).
  • Adjust how a known format is detected: e.g., teach BetterZip about a non-standard extension you use.

Where the definitions live

Built-in formats ship as JSON files inside the app bundle’s Formats/ resource folder and loaded into the BetterZip settings on the first launch.

You can inspect and modify format definitions in Settings > Helpers. The + button opens an inline JSON editor sheet for a new entry, and double-clicking an existing row opens the same sheet to edit it. The Restore Defaults button discards every change you’ve made to the built-in definitions and re-reads them fresh from the app bundle; the custom formats you’ve added yourself are kept. It doesn’t make a backup first, so reach for it only when you want to throw those edits away.

Tags 1–999 are reserved for built-ins; user definitions are auto-assigned a tag of 1000 or higher.

Updates and backups

Built-in definitions can change between BetterZip versions. When you install an update that ships a changed definition, BetterZip refreshes your stored copy to match it on the next launch. Custom formats you’ve added yourself (tag 1000 and up) are never touched.

Before it replaces a built-in, BetterZip backs up the copy you currently have – whether that’s the previous stock version or one you customized in Settings > Helpers – so an update can never silently discard your edits. Backups go into a timestamped folder:

~/Library/Application Support/com.macitbetter.betterzip/Format Backups/<date and time>/<format>.json

Each update run creates one folder, with one JSON file per format it replaced. BetterZip also writes a line to the Transcript window – in a log named Format Updates – pointing at the backup, so you can find your old definition and paste any changes back into the JSON editor if you still want them.

A minimal example

Here’s a read-only definition that just teaches BetterZip about a new extension via the bundled XADMaster framework:

{
  "class": "xad",
  "format": "sit",
  "name": "StuffIt Archive",
  "tag": 1001,
  "extensions": ["sit", "sitx"]
}

And a write-capable format that calls an external tool, using factor-based compression levels and placeholder substitution:

{
  "class": "tar",
  "format": "tzst",
  "name": "TAR, Zstandard compressed",
  "tag": 1002,
  "installPath": "/usr/local/bin/zstd",
  "canSave": true,
  "extensions": ["tzst", "zst"],
  "magicBytes": [
    { "start": 0, "hex": true, "bytes": "28B52FFD" }
  ],
  "compress": {
    "factors": [
      { "standardTitleTag": 1, "position": 1, "weight": 5,  "options": ["-1"] },
      { "standardTitleTag": 2, "position": 2, "weight": 6,  "options": [] },
      { "standardTitleTag": 3, "position": 4, "weight": 75, "options": ["-19"] }
    ]
  }
}

BetterZip substitutes placeholders like $ARCHIVE, $FILES, $PASSWORD, $THREADS, and $LISTFILE at runtime. The handler is picked by the class field – xad, tar, 7z, rar, xar, hdiutil, or mime – which decides whether the work happens in-process via a bundled framework or by shelling out to a CLI tool.

Going further

For the full schema – every field, every placeholder, the handler classes, the multi-volume schemes, error handling, encryption detection – see the format specification reference.

Sharing definitions

If you create a definition for a format and would like to share it with other users, get in touch: .