From 8573660394e46556751978841543b4cc34747a72 Mon Sep 17 00:00:00 2001 From: David Newhall II Date: Wed, 26 Aug 2026 01:52:57 -0700 Subject: [PATCH 1/3] Document xt install, flags, and job files. Replace the 2024 stub with usage that matches the CLI and job struct, and link it from the install chooser and navbar. Co-authored-by: Cursor --- docs/install/choosemethod.md | 2 + docs/xt.md | 114 +++++++++++++++++++++++++++++++++-- docusaurus.config.js | 5 ++ 3 files changed, 115 insertions(+), 6 deletions(-) diff --git a/docs/install/choosemethod.md b/docs/install/choosemethod.md index 82a2830..8aba882 100644 --- a/docs/install/choosemethod.md +++ b/docs/install/choosemethod.md @@ -21,6 +21,8 @@ reside. Read more about that on the [Docker page](docker#folder-watcher). - [macOS](/docs/install/macos) - [Windows](/docs/install/windows) +Need a one-shot command-line extractor instead of a daemon? See [xt](/docs/xt). + :::tip[CPU Hog] Unpackerr uses a lot of CPU while extracting, and tends not to work well when running on smaller systems like Synology NAS devices. Running Unpackerr on diff --git a/docs/xt.md b/docs/xt.md index 66ed03d..06c7d36 100644 --- a/docs/xt.md +++ b/docs/xt.md @@ -1,13 +1,115 @@ --- id: xt title: eXtractor Tool -description: Recursively decompress archives +description: Recursively decompress archives with the xt command-line tool. --- -`xt` is a light-weight command line utility built using the same technology as Unpackerr. -Use this tool when you need to decompress a folder (or folders) full of archives. -It recursively decompresses archives from any file system path(s) provided. +`xt` is a one-shot command-line extractor built on the same +[xtractr](https://github.com/golift/xtractr) engine as Unpackerr. +Give it files or folders; it recursively decompresses archives it finds. -GitHub Repo: https://github.com/Unpackerr/xt +It is not a daemon and it does not poll Starr apps. Use Unpackerr when you want +ongoing queue or folder watching. Use `xt` when you want to extract a path now. -This page is new and needs updates/more info. Jan 2024. +GitHub: [Unpackerr/xt](https://github.com/Unpackerr/xt) + +## Install + +### Linux + +Alpine and Arch packages are on the [releases](https://github.com/Unpackerr/xt/releases) +page. On Debian/Ubuntu and RedHat/Fedora, install the GoLift repo and `xt`: + +```shell +curl -s https://golift.io/repo.sh | sudo bash -s - xt +``` + +### macOS + +```shell +brew install golift/mugs/xt +``` + +A binary is also on the [releases](https://github.com/Unpackerr/xt/releases) page. + +### Windows + +Download an `exe` from the [releases](https://github.com/Unpackerr/xt/releases) page +and put it in your `PATH`. It runs in a command or terminal window only. + +### FreeBSD + +Download a FreeBSD binary from the +[releases](https://github.com/Unpackerr/xt/releases) page and extract it into your +`PATH`. `/usr/local/bin` is a good location. + +### Go + +```shell +go install golift.io/xt@latest +``` + +## Usage + +```shell +xt [options] [path [path] [path] ...] +xt --job-file /tmp/job1 -j /tmp/job2 +``` + +Paths may be files to extract or directories to search. + +| Flag | Meaning | +| --- | --- | +| `-o`, `--output` | Directory to write extracted files. Default: current directory. | +| `-S`, `--squash-root` | If the archive root is a single folder, move its contents up. | +| `-d`, `--max-depth` | How deep to recurse. `0` is unlimited; `1` disables recursion. | +| `-m`, `--min-depth` | Only extract archives this many subdirectories deep or deeper. | +| `-P`, `--password` | Password for encrypted RAR/7z. Repeat the flag for more passwords. | +| `-e`, `--extension` | Only extract these extensions (include the leading dot). Repeatable. | +| `-j`, `--job-file` | Extra jobs from xml, json, toml, or yaml. TOML is the default. | +| `-p`, `--preserve-paths` | Recreate the input directory hierarchy under `--output`. | +| `-V`, `--verbose` | Print extracted file paths. | +| `-D`, `--debug` | Debug output. | +| `-v`, `--version` | Print version and supported extensions, then exit. | +| `-h`, `--help` | Usage. | + +`-e` values must match a supported extension. Unknown extensions are ignored. +Run `xt -v` to print the live list. + +## Job files + +CLI flags build one job. Job files define one or more jobs with their own paths, +output, depths, and passwords. Formats: xml, json, toml, yaml (toml if the +extension is missing). + +If `include_suffix` is set, `exclude_suffix` is ignored. + +Example TOML: + +```toml +paths = [ '/path1', '/another/path' ] +output = '.' +passwords = [ 'password1', '''password"With'Specials!''', 'pass3'] +exclude_suffix = ['.iso', '.gz'] +include_suffix = ['.zip', '.rar', '.r00'] +max_depth = 0 +min_depth = 1 +file_mode = 644 +dir_mode = 755 +squash_root = false +verbose = false +debug_log = false +preserve_paths = false +``` + +JSON and YAML use camelCase for some keys (`excludeSuffix`, `debugLog`, +`preservePaths`). XML uses `path` / `password` (singular) for the lists. + +## Formats + +Same engine as Unpackerr: zip, rar (including `.r00`), 7z, tar, gz, bz2, xz, +zst, iso, and others. `xt -v` prints every extension xtractr currently +recognizes. + +ISO extraction is always available in `xt`. Unpackerr's `extract_isos` setting +does not apply here. diff --git a/docusaurus.config.js b/docusaurus.config.js index 9c3adfe..360f4f7 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -76,6 +76,11 @@ const config = { label: 'GitHub', position: 'right', }, + { + to: 'docs/xt', + label: 'xt', + position: 'right', + }, ], }, footer: { From 14af4d849327c6c23372f1255953f4f619b8dd92 Mon Sep 17 00:00:00 2001 From: David Newhall II Date: Wed, 26 Aug 2026 16:02:51 -0700 Subject: [PATCH 2/3] List every xtractr archive type on the xt page. Co-authored-by: Cursor --- docs/xt.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/xt.md b/docs/xt.md index 06c7d36..1987e6e 100644 --- a/docs/xt.md +++ b/docs/xt.md @@ -107,9 +107,18 @@ JSON and YAML use camelCase for some keys (`excludeSuffix`, `debugLog`, ## Formats -Same engine as Unpackerr: zip, rar (including `.r00`), 7z, tar, gz, bz2, xz, -zst, iso, and others. `xt -v` prints every extension xtractr currently -recognizes. - -ISO extraction is always available in `xt`. Unpackerr's `extract_isos` setting -does not apply here. +Same [xtractr](https://github.com/golift/xtractr) engine as Unpackerr. Detected by +file extension: + +- Zip: `zip` +- RAR: `rar`, `r00` +- 7-Zip: `7z`, `7z.001` +- tar: `tar`, `tar.gz`, `tgz`, `tar.bz2`, `tbz`, `tbz2`, `tar.xz`, `txz`, `tar.z`, `tz`, `tlz` +- gzip / bzip2 / xz / zstd: `gz`, `gzip`, `bz2`, `xz`, `zst`, `zstd` +- Other compressors: `lz4`, `lz`, `lzip`, `lzma`, `lzma2`, `z`, `br`, `brotli`, `s2`, `snappy`, `sz`, `zlib`, `zz` +- Packages and images: `iso`, `cpio`, `cpio.gz`, `cpgz`, `ar`, `deb`, `rpm` +- Cue sheets (FLAC splits): `cue`, `cue.txt` + +Multi-file and password-protected archives work with RAR and 7-Zip. +ISO extraction is always available in `xt`; Unpackerr's `extract_isos` setting does +not apply here. `xt -v` prints the extension list from the binary you have. From 0d60690e1f4f04fd38dc25aa6b600f312353e126 Mon Sep 17 00:00:00 2001 From: David Newhall II Date: Wed, 26 Aug 2026 17:08:38 -0700 Subject: [PATCH 3/3] Wrap a compressor list line so markdownlint MD013 passes. Co-authored-by: Cursor --- docs/xt.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/xt.md b/docs/xt.md index 1987e6e..ac8c51d 100644 --- a/docs/xt.md +++ b/docs/xt.md @@ -115,7 +115,8 @@ file extension: - 7-Zip: `7z`, `7z.001` - tar: `tar`, `tar.gz`, `tgz`, `tar.bz2`, `tbz`, `tbz2`, `tar.xz`, `txz`, `tar.z`, `tz`, `tlz` - gzip / bzip2 / xz / zstd: `gz`, `gzip`, `bz2`, `xz`, `zst`, `zstd` -- Other compressors: `lz4`, `lz`, `lzip`, `lzma`, `lzma2`, `z`, `br`, `brotli`, `s2`, `snappy`, `sz`, `zlib`, `zz` +- Other compressors: `lz4`, `lz`, `lzip`, `lzma`, `lzma2`, `z`, `br`, `brotli`, + `s2`, `snappy`, `sz`, `zlib`, `zz` - Packages and images: `iso`, `cpio`, `cpio.gz`, `cpgz`, `ar`, `deb`, `rpm` - Cue sheets (FLAC splits): `cue`, `cue.txt`