Docs

User guide

How to get started with Octal and DriveBench, and find your way around. This guide grows as the apps do, so tell us what's missing.

Getting started

Octal shows one folder, or two panes side by side. Each pane browses independently: set one to your source and the other to your destination, then drag or use ⌘C / ⌘V to move files between them. Switch between List, Tree and Gallery from the view control in each pane's toolbar, and press Space for a Quick Look preview.

Keyboard shortcuts

Shortcuts act on the active pane, the one with the highlighted selection. Tab switches between the two panes. Most of these are also in the menus, with the shortcut shown next to each item.

Windows and panes

Moving around

Viewing

Files

On most Mac keyboards the top row controls brightness and volume, so hold fn to use F5–F8. To make them work on their own, turn on Use F1, F2, etc. keys as standard function keys in System Settings ▸ Keyboard ▸ Keyboard Shortcuts… ▸ Function Keys.

Connecting to servers

Choose Go ▸ Network (⌘K) to see servers discovered on your network, or click Connect to Server… there to enter an address.

• SMB / AFP / NFS / WebDAV: mounted through macOS. Enter the host and your credentials; they're saved to the macOS Keychain.
• SFTP / FTP: connect over SSH or classic FTP, with saved connections.
• Amazon S3 and compatible: add your access key and secret, or use a profile from ~/.aws. MinIO, Backblaze B2, Cloudflare R2 and other S3-compatible endpoints work too.

You can open a file on SFTP, FTP or S3 in your own editor, and each save goes back to the server.

To check a connection, right-click a server in the Network panel, or a row in Current Connections, and choose Ping. A window shows live round-trip times, packet loss and a chart.

Working with git

Browse into any git working tree and Octal shows the current branch plus change badges next to modified, added and untracked files. Open a file's history to view diffs, the log and commits, without a separate git client.

Octal runs the git already on your Mac rather than bringing its own, so git needs to be installed. Either of these works:

• The Xcode Command Line Tools: run xcode-select --install in Terminal. Xcode itself also includes git.
• Homebrew: brew install git. MacPorts' git works too.

Without git, Octal hides its git features rather than prompting you to install the developer tools. Settings ▸ Git says whether it found one.

Searching inside files

Use content search to find text inside files. Matches appear with a preview and syntax highlighting, so you can confirm the hit before you open anything.

Folder compare and sync

Select two folders and choose Compare to see exactly what differs. From there, sync one way or both ways. You see the list of changes before anything is written.

Batch rename

Select a group of files and open Batch Rename. Stack rules (find and replace, numbering, case, insert) and the preview shows every new name. A rename that would clash with another name won't apply, and ⌘Z undoes the whole rename.

Metadata and extended attributes

The Get Info panel shows full metadata: dimensions, EXIF, permissions, dates and location. Expand Extended attributes to view and edit xattrs as text, plist XML or hex, with guardrails around protected system keys.

Custom actions

Custom actions add your own commands to the file context menu. Each one runs a command-line tool on the selected files, with its progress shown in the Activity panel. Octal comes with a few, such as Compress (ZIP, tar.gz and more) and Mirror to Other Pane (rsync), and you can add as many as you like.

An action is a small JSON file in ~/.octal/actions/. To get there, open Settings ▸ Custom Actions and click Open Folder. Octal notices new and changed files by itself; Reload is there too, and any file it can't read is listed with the reason. A file holds one action, or an array of them ([ { … }, { … } ]) to keep related actions together. // and /* … */ comments are allowed. The same reference is in the app under Help ▸ Action Format Reference.

A minimal action

{
  "id": "open-in-vscode",
  "title": "Open in VS Code",
  "icon": "chevron.left.forwardslash.chevron.right",
  "command": "/usr/bin/open",
  "args": ["-a", "Visual Studio Code", "${selectedPath}"]
}

Octal runs the command directly, not through your shell, so command must be an absolute path. Homebrew tools are in /opt/homebrew/bin on Apple silicon and /usr/local/bin on Intel.

Fields

Only id, title and command are required.

Tokens

Any ${name} in a text field is replaced when the action runs. An unknown token becomes empty.

When an action is offered

appliesTo limits the action to the selections it makes sense for. Leave out any part you don't need. File kinds and extensions must match every selected item.

Output, inputs, progress and cleanup

output names the file the action creates and binds it to ${output}. With "unique": "number" an existing Archive.zip leads to Archive 2.zip; "copy" gives Archive copy.zip. Without unique the path is used as it is and may overwrite a file.

"output": { "path": "${activePaneDir}/${selectedBasename}.mp4", "unique": "number" }

inputs shows a small form before the action runs. Each entry needs a name, and can have a label, a default and a placeholder. Give it options for a pop-up menu, unit for a number with a fixed unit, or units for a number with a choice of unit; otherwise it's a text field.

"inputs": [
  { "name": "format", "label": "Format", "options": ["png", "jpeg", "webp"], "default": "png" },
  { "name": "scale",  "label": "Scale",  "units": ["%", "px"], "default": "100" }
]

progress defaults to a spinner with the tool's latest line of output. { "kind": "regex", "pattern": "([0-9]+)%" } reads a percentage from the output. For tools that print nothing, { "kind": "outputSize", "path": "${output}", "ratio": 0.5 } estimates progress from how big the output file has grown, against the input's size times ratio.

cleanup deletes files when a run ends a certain way. By default that's when it's cancelled or fails, which is right for a half-written file. Add "completed" to on to remove temporary files after a successful run.

"cleanup": { "delete": ["${output}"], "on": ["cancelled", "failed"] }

A complete example

Converts a video to MP4 with ffmpeg, writes the result next to the original without replacing anything, and refreshes the folder when it's done.

{
  "id": "to-mp4",
  "title": "Convert to MP4",
  "menu": "Video",
  "icon": "film",
  "command": "/opt/homebrew/bin/ffmpeg",
  "args": ["-nostdin", "-y", "-i", "${selectedPath}",
           "-c:v", "libx264", "-crf", "23", "-c:a", "aac", "${output}"],
  "appliesTo": {
    "kinds": ["file"],
    "extensions": ["mov", "mkv", "avi", "webm"],
    "selection": "single",
    "providers": ["local"]
  },
  "output": { "path": "${activePaneDir}/${selectedBasename}.mp4", "unique": "number" },
  "cleanup": { "delete": ["${output}"] },
  "refreshes": ["${activePaneDir}"]
}

Reveal in Octal from Finder

Octal adds a Reveal in Octal service, which opens the files you've selected in Finder (or any other app) in an Octal window. macOS turns new file services off until you enable them, so it won't appear in Finder's Services menu at first. To turn it on:

1. Open System Settings ▸ Keyboard and click Keyboard Shortcuts…
2. Select Services in the list on the left.
3. Expand Files and Folders and tick Reveal in Octal.

You can also give it a keyboard shortcut there. After that, right-click a file in Finder and choose Services ▸ Reveal in Octal.

Testing drive speed with DriveBench

Octal DriveBench measures how fast a drive reads and writes. It runs five tests: sequential write and read, random 4K write and read, and small-file operations. The same tests are built into Octal.

In Octal

Right-click a volume in the sidebar and choose Test Drive Speed…. Pick the tests and the test size (5 GiB by default); Advanced has the block sizes and the cache bypass. The test runs in the Activity panel (⇧⌘T) with a live chart, and you can keep working while it runs. If the drive is busy with a copy, Octal warns you, since the results will be lower, but it still lets you run the test. When it finishes, Share makes a report image, and Open in DriveBench opens the app on the same drive.

In DriveBench

• Choose a drive from the volume menu at the top of the window, or Choose Folder… to test a particular folder, such as one on a network share.
• Set the size, the block sizes and Bypass cache, then click Run Benchmark. Stop ends a run early; the test data is removed either way.
• Every run is kept under Previous runs. Click Compare, select two or more runs, and they're shown side by side.
• Share Report Image… saves or shares an image of a run, with a QR code back to this site. Drives appear by model, never by your volume name.

Reading the results

Sequential speeds are the sustained rate, measured once the drive's cache has filled; the peak shows what the drive manages before that. Random results are in IOPS, operations per second, which matters more than MB/s for apps and the system. A large gap between peak and sustained is normal for many SSDs and most USB drives. To see where a drive's cache runs out, or to check that it really holds what it claims, choose Fill disk as the size.