Create and extract archives

A .sqz archive is one file that holds a folder (or a single file) and any number of snapshots of it. This page covers creating, testing, listing and extracting.

Create#

sqz c [mode] [-j N] [--block MiB] <file-or-folder> <archive.sqz>

Examples:

sqz c C:\data data.sqz                  # default mode: --max
sqz c --balanced -j 4 C:\data data.sqz  # everyday mode, 4 threads
sqz c --fast ~/projects projects.sqz    # quickest

• Mode is one of --fast, --smart, --balanced or --max (the default). See Modes and tuning.
• -j N sets the number of threads. By default Fast uses every core and the other modes use up to 8.
• For inputs of 1 GiB or more, SQZ prints an estimate first. --no-estimate skips it; --estimate forces it for smaller inputs.

The new archive is written under a temporary name and appears under its real name only when it is complete, so an interrupted run never leaves a half-written .sqz. SQZ refuses to replace an existing file.

What gets stored#

Files and their contents, folders (including empty ones), symlinks (recorded, never followed), hard links, permission bits and modification times to the sub-second. Not stored yet: file owners, ACLs, extended attributes and sparse regions. Sockets, devices and names that are not valid UTF-8 are skipped with a warning. See Known limits.

Test#

sqz t data.sqz
sqz t -s 2 data.sqz                     # one snapshot
sqz t --file docs/report.txt data.sqz   # one file

Testing decodes everything and checks every chunk and every file against its BLAKE3 digest, exactly as extraction does, but writes nothing. Run it after copying an archive to another disk or before deleting the originals.

List#

sqz l data.sqz
sqz l -s 1 data.sqz

Lists the files in a snapshot (the latest by default) and the snapshots in the archive.

Extract#

sqz x [-s N] [-j N] [--file PATH]... <archive.sqz> <output-folder>

sqz x data.sqz C:\restore
sqz x -s 1 data.sqz C:\old-snapshot
sqz x --file docs/report.txt --file docs/budget.xlsx data.sqz C:\two-files

• --file PATH picks an exact path inside the archive, with forward slashes, as sqz l shows it. Repeat it for several files. A path that is not in the archive is an error before anything is written. Only the blocks those files need are decoded.
• -s N picks a snapshot, 1 being the oldest. The latest is the default.
• --estimate prints the time, memory and free space extraction will need before it starts.

Checks before anything is written#

Before writing a single file, extraction checks the destination and stops with one error, leaving nothing behind, when:

• an entry already exists there (existing folders are reused, existing files are never overwritten);
• the archive holds names that differ only in letter case, such as Readme.txt and README.txt, and the destination ignores case, as NTFS and APFS do by default (SQZ checks with a probe file);
• on Windows, a name Windows cannot create: CON, aux.txt, COM1, names containing < > " | ? * or control characters, or ending in a dot or space;
• there is not enough free space for the files plus 1% and 16 MiB.

The error names up to five of the paths involved. Use --file to leave out the ones that clash, or extract into a different folder.

The order of restoring#

Regular files come first, each verified and then given its real name, time and permissions. Then folders, hard links and symlinks, and finally the times and permissions of the folders, deepest first. Symlinks that would point outside the output folder (absolute targets, .. that climbs out, or targets with \ or :) are skipped with a warning. setuid, setgid and sticky bits are never granted. On Windows, folder times are not restored and symlinks are created only if your account may create them.

Long paths on Windows#

Paths longer than Windows' old 260-character limit restore normally.

Extract to a new, empty folder#

Restores go somewhere new. SQZ never overwrites, and publishing each verified file needs a drive that supports hard links. Keep the output folder under your control and do not change it while extraction runs.

Exit codes#