Files, jobs & viewers

Ctrl-S opens quick find. Type a name or a glob such as *.rs; Down and Up move between matches, Insert marks a match, Ctrl-A marks all matches, and Enter or Esc closes the search. Matching ignores case unless the query contains uppercase letters.

Copying, moving, and deleting

F5, F6, and F8 start copy, move, and delete jobs. Alt-J opens the list of jobs, where you can pause or cancel them.

The Delete dialog starts on No, so Enter on its own keeps the files. To delete them, press Y, or move to Yes with Tab or an arrow key and press Enter.

While the Delete dialog asks, Borg counts the files you are about to remove and shows their number and size under the question. Counting stops after 3 seconds, and then the line starts with At least. Borg also looks for programs that have those files open, run from them, or work in one of those folders, and names them. A program that keeps a deleted file open keeps its disk space too, until it closes the file. Press K to open the activity monitor on the first of them with Signal or priority, and stop it before you delete. Borg sees the programs your user may inspect, which on most systems means your own. Files in archives, containers, and remote panels are deleted without these checks.

The Copy dialog has an Optimize copying for hard drives checkbox. Press Tab to reach it and Space to toggle it, or click it. It is unchecked for every new copy. In this mode, Borg reads small files into memory in batches and then writes each batch, which can cut down on disk seeking when copying within a single hard drive. A batch holds up to 64 MiB of file data or 4,096 files; files larger than 1 MiB are copied normally. How much it helps depends on the drive, the file system, and OS caching, and it may be slower when copying between separate drives. When a file name already exists: o overwrites, s skips, k keeps both, a overwrites all, n skips all, and Esc cancels. Copies are written to temporary files and renamed once they are complete.

Long jobs and drives

Borg knows what kind of drive each folder lies on: a hard drive, an SSD, a RAM disk, a network share such as NFS, SMB or sshfs, or the machine a remote panel shows. On macOS it asks diskutil and hdiutil, and on Linux it reads /proc/self/mountinfo and the device’s flags in /sys. Ctrl-L shows the drive and its filesystem in the Drive row, and the Speed row says how fast Borg expects it to read and write.

Before a job writes anything, Borg works out how long it will take from the bytes it reads and writes on each drive and the time compressing takes. When a copy, a move to another drive or an unpack would take more than 2 minutes, or a change to an archive more than 20 seconds, the Long job dialog says about how long and on which kind of drive, and waits:

• Start (s) runs the job.
• Always for this file (f) runs it and stops asking about this archive. Unpacking and changes to an archive offer it.
• Always on this kind of drive (d) runs it and stops asking about work on drives of this kind.
• Cancel (c) stops before the first write.

A save from the editor into an archive asks over the editor, which gets the keys back once you answer.

Until Borg has measured a drive, it expects the usual speed of its kind: about 120 MB/s for a hard drive, 900 MB/s for an SSD, 4 GB/s for a RAM disk, 60 MB/s for a network share and 10 MB/s for a remote machine. Every job that runs for at least 2 seconds and moves at least 64 MiB teaches Borg the drive’s real speed, and the Drive row then says measured speed. A job that spends its time compressing teaches it nothing about the drive.

Borg keeps the speeds and your answers in drives.json in its state folder, with up to 256 archives. The file is readable by you alone, since it names the archives you answered about. Every Borg you have open shares it: each one reads it when it starts and again right before it writes, so what one Borg learned or was told stays when another writes. The Long jobs row of Ctrl-L says whether Borg asks first on that drive. F9 → Options → Ask before long jobs again forgets every Always answer, those given in other Borgs too. A Borg that is already open keeps the answers it has until it next writes the file or you start it again.

Viewer and quick view

F3 opens the viewer. With the System plugin on, F3 on a .pcap, .pcapng or .cap file opens the network screen’s traffic viewer instead (see Capturing traffic). In text files, the arrow keys and PgUp/PgDn scroll, w turns line wrapping on or off, and Esc or q closes it. In images, Left/Right or p/n show the previous or next image. Borg uses the terminal’s image protocol when there is one; other terminals show the image as colored blocks.

Ctrl-Q shows a quick preview in the other panel. Tab moves into it, where the arrow keys, PgUp/PgDn, Home/End, and the mouse wheel scroll; Tab or Esc goes back to the file list. Ctrl-L shows file information. F3 opens a text preview in the full viewer, and closing the viewer returns to the preview with your position, wrapping, source mode, and hex rows kept. Both read files the same limited way, so opening a large text file reads only around the first page and stays fast however big the file is. On a result of a search for text, the preview opens at the file’s first match instead, with the query marked as the find bar marks it, and reads only around that match.

Both text viewers highlight common programming languages, markup, and configuration files, including Rust, Python, JavaScript, TypeScript/TSX, Go, C/C++, Java, C#, Ruby, PHP, Lua, SQL, HTML/CSS, JSON, YAML, TOML, shell scripts, and Dockerfiles. Markdown opens formatted by default; press s or F4 in either viewer to switch to the source. Headings, emphasis, lists, task lists, links, tables, and fenced code blocks are supported. Markdown files larger than 2 MiB open as source to keep memory use down.

JSON opens laid out with one value per line, with its keys in their original order and its numbers exactly as written, which helps most with files written on a single line. Press s or F4 to see the file as written. JSON Lines files (.jsonl, .ndjson) are laid out one record at a time. JSON larger than 16 MiB, or JSON that does not parse, opens as written.

Press h in the text viewer or in the quick view to see the file’s bytes as hex rows, and press it again to go back to the text. A binary file, which Borg spots by a zero byte in its first 4 KiB, opens as hex rows in both, and h shows its text. Each row starts with its offset in the file, then shows its bytes in hex and the same bytes as text, with a dot for each byte that does not print. Offsets and zero bytes are dimmed. A row holds as many bytes as fit the width: 64, 32, 16, 8, 4, 2 or 1, with a wider space after every eighth byte. Borg reads only the rows on the screen, so the arrow keys, PgUp/PgDn, Space, Home and End move through a file of several gigabytes at once. The find bar works in hex rows too and marks each match in both columns. In hex, Markdown and JSON files show their bytes as written.

In the viewer, an entropy strip runs down the right edge of the hex rows. Entropy says how varied the bytes are, from 0 bits per byte for one byte repeated to 8 for bytes as random as compressed, encrypted or packed data. Text is usually near 4.5, and code between 5 and 6.5. The strip covers the whole file from top to bottom. Each cell’s bar is as long as the highest entropy in its part of the file, faint below 4 bits per byte and bold red from 7.2, and the cells of the bytes on the screen are marked as on a scrollbar. The status line gives the entropy at the page and whether it is low, typical or high. Press ] and [ to jump to the next and previous run of high-entropy blocks, or click the strip to go to that part of the file.

Borg reads the entropy in the background in blocks of 4 KiB. A file up to 256 MiB is read whole, and a larger one is sampled at 65,536 evenly spaced blocks, so memory use stays the same however big the file is. High entropy where you expect code, headers or tables can mean packed or encrypted data hidden there. Compressed media, archives, encrypted volumes and key stores are high all the way through, so read the strip against what the file should hold.

Archives

Press Enter on an archive to open it as a folder. Borg opens files whose names end in .zip, .7z, .rar, .tar, .tar.gz, .tgz, .tar.bz2, .tbz2, .tbz, .tar.xz, .txz, .tar.zst or .tzst, and single compressed files ending in .gz, .bz2, .xz or .zst, which open as a folder holding the one file. Ctrl-PgDn opens an archive too, and F3 on the archive itself still shows its bytes in the viewer. The panel’s title gets a badge such as ▤ zip that names the format Borg found in the file’s first bytes, and the path goes on inside the archive. Folders inside show the size of what they hold. Left, Enter on .. or Ctrl-PgUp at the archive’s top takes you back to the folder that holds it, with the cursor on the archive. When the archive was deleted or no longer reads, going up from any folder of it takes you back there too, and the notice says why.

To list an archive, Borg reads what it holds, which for a compressed tar means reading the whole file. While a large archive is read, the panel’s footer shows how far Borg got, and Esc stops reading and goes back. Borg remembers the listings of the last 4 archives as long as their files keep the same size and time, so going in and out again is instant. Archives with more than 1,000,000 entries do not open.

F3 or Enter on a file inside unpacks it into a private folder in Borg’s runtime folder and opens it in the viewer. The unpacking runs as a job, so a large file shows its progress, and Esc cancels it. Borg deletes the unpacked file as soon as the viewer has it open.

F4 on a file inside opens it in the editor, and Alt-E opens it in the panel’s editor. Borg unpacks the file into the same private folder, and the editor’s title shows its path inside the archive. Each save writes the file back into the archive as a job, and the editor says so (“Saved. Writing it into site.zip.”). When the archive does not take it, the notice says why and where your edit stays.

F5 copies the marked files and folders out of the archive into the other panel’s folder, or into the folder you type in the Copy dialog. Extract here and Extract to other panel in the File menu (F2) unpack the whole archive under the cursor into this panel’s folder or the other panel’s. Either way the files land in a folder on this machine, and the job shows up in Alt-J with its progress, rate and time left. It asks about names that already exist as a copy does, writes each file under a temporary name until it is complete, and stops each file at the size the archive gives it.

Borg changes zip, 7z and tar archives, compressed or not. F5 or F6 from a folder of this machine copies or moves the marked files into the archive the other panel shows, or into the folder of it you type in the dialog. F7 makes a folder in the archive, and F8 deletes the marked entries after asking. F6 to a name in the same archive renames or moves the entries there, and F6 to a folder of this machine moves them out: they unpack there and then leave the archive. Names that already exist in the archive are asked about as a copy asks, and so are names two of the files you copy share, as files from search results or a collection can. A rename to a name the archive holds stops with a notice. A move deletes only what arrived whole, so a file you skip stays where it was, and so does one that a later file of the same name replaced.

Each change runs as a job in Alt-J. Borg writes the changed archive beside the original under a temporary name, reads it back, and then puts it in the original’s place with the same permissions. The read-back checks a zip’s or 7z’s list of entries and every entry of a tar. A file goes in as it is when Borg writes it, so a file you save again while the job waits for your answer goes in with its latest contents. A change that fails or that you cancel leaves the archive as it was. Entries the change keeps are copied as they are stored: a zip copies their compressed data, and a 7z copies every solid block that keeps all its entries and packs again only the blocks that lose one. A compressed tar is unpacked and packed again whole, then unpacked once more to read it back, so changing a large .tar.xz takes about as long as making it and unpacking it. A zip or plain tar that only gains entries is copied and the new entries follow the last one, and on APFS, Btrfs, XFS and bcachefs that copy is instant. Before a change that would take long, Borg asks first (see Long jobs and drives).

In an encrypted zip or 7z archive, new entries are encrypted with AES-256 and the password you opened the archive with, and a 7z that hides its list of entries keeps it hidden. Entries the change keeps stay as they were.

RAR archives and single compressed files such as .gz stay read only, and changing them says so. Ctrl-Q and Compress… do not work inside an archive. An archive inside an archive opens once you copy it out. The shell stays in the folder that holds the archive, and a saved session reopens that folder with the cursor on the archive.

Encrypted zip and 7z archives ask for the password when they open. In the Password dialog each character you type shows as glitch noise that keeps changing and flares with every key. The noise depends only on how many characters you typed. The dialog asks again when the password is wrong, and Esc leaves the archive. Borg keeps the password in memory while the panel shows the archive and never writes it anywhere. Extract here has no way to ask for one, so for an encrypted archive press Enter on it, type the password, and copy the files out with F5.

Before it writes anything, Borg adds up what the chosen entries unpack to and asks first when that is more than 1 GiB and more than 100 times the archive’s size, or more than 100,000 files, which is how zip bombs look. It also asks when the destination has less free space than the files need, and a change to an archive asks when its drive lacks room for the new archive beside the old one. Unpack anyway (u) goes ahead, and Cancel stops before the first file. Entries with absolute paths, .. in their paths, or device files are left out with a notice, and no entry or link in an archive can make Borg write outside the destination folder.

Borg reads zip, 7z and the tar family itself. RAR archives go through 7-Zip (7zz or 7z) or bsdtar, whichever Borg finds first, and macOS comes with bsdtar. When none is installed, Enter on a RAR archive offers to install bsdtar. The Install bsdtar dialog works like the one for tcpdump in Capturing traffic: it shows the exact command for your package manager, and Enter types it into Borg’s shell. Borg also looks for bsdtar in Homebrew’s libarchive folder, which Homebrew leaves off PATH. Encrypted RAR archives do not open yet.

Editor

F4 opens the selected file in Borg’s editor, and Shift-F4 opens it in $VISUAL or $EDITOR. The editor keeps the file’s line endings and indentation, highlights code like the viewers do, and shows line numbers. Shift with the arrow keys selects text; Ctrl-C, Ctrl-X, and Ctrl-V copy, cut, and paste through Borg’s clipboard, and text pasted from the terminal goes in exactly as it is. Ctrl-Z and Ctrl-Y undo and redo, and Tab and Shift-Tab indent and unindent. F2 or Ctrl-S saves through a temporary file, so a file is never left half written. Files that are not UTF-8 text, or are larger than 32 MiB, open in the viewer instead. Lines longer than 20,000 characters, such as minified code, are not highlighted, and only the part of a line that is on screen is drawn, so even a large file written on a single line edits without delay. Alt-Shift-F lays out a JSON file with one value per line, using the file’s own indentation, in one step that Ctrl-Z undoes; JSON that does not parse is left as it is, and the status line says where parsing stopped.

The editor asks its questions in dialogs over the text: Tab moves between fields and buttons, Enter confirms the selected one, Esc cancels, and you can click any of them. Ctrl-F or F7 finds text with the find bar described below. Ctrl-R or F4 replaces, with the same switches as the find bar: Enter replaces the match and moves to the next one, Skip leaves it, and Alt-A or All replaces every match in one step that a single Ctrl-Z undoes. With a regular expression, $1 in the replacement puts back what its first group matched. Ctrl-G goes to a line. Esc closes the editor, and asks first whether to save or discard unsaved changes; if the file changed on disk since you opened it, Borg asks whether to overwrite it or reload it. A click places the cursor, dragging or Shift-clicking selects, a double-click selects a word, and the wheel scrolls; the keys shown in the status line can be clicked too.

Alt-E opens the selected file in Borg’s editor inside the active panel, in place of its files, so you can edit two files side by side, or a file next to the folder it is in. In search results and collections, Alt-E opens the editor in the other panel, so the list stays in view. Alt-E on another result opens it in place of the file there. When that file has unsaved changes, Alt-E brings its editor forward and asks whether to save them. F6 moves from a panel’s editor to the other panel, and Tab goes back to the editor from the file list. Text copied with Ctrl-C in one editor pastes with Ctrl-V in the other. While an editor has focus, the shortcut bar shows the editor’s keys, and the panel keys come back with the file list. Ctrl-O shows the console from an editor too, and F9 opens the menus. Esc or F10 closes the editor and gives the panel back its files; Quit first asks about each panel editor with unsaved changes. Quick view and file information need the other panel, so they wait until its editor is closed. An editor opened beside results gives the focus back to them when it closes, and brings back the quick view or file information they showed.

The viewer and the editor find text the same way. In the viewer, /, F7, or Ctrl-F opens a find bar in the status line; in the editor, Ctrl-F or F7 does. Borg searches as you type, starting from where the bar opened: every match on the screen is marked, the current one stands out, and the bar counts them (3 of 17). Enter, Down, or F3 goes to the next match, and Shift-Enter, Up, or Shift-F3 to the previous one; after the last match, the search continues from the other end and says so. Alt-C matches case exactly (otherwise a lowercase query matches any case), Alt-W matches whole words, and Alt-R reads the query as a regular expression; you can click the switches too. Ctrl-P and Ctrl-N bring back recent queries. Esc closes the bar; after that, n and N in the viewer, or F3 and Shift-F3 in the editor, step through the matches. In a large file, the viewer searches in the background, shows how far it has got, and stops when you press Esc. It counts matches in files up to 64 MiB, up to 10,000 of them.