xzip

xzip is a ZIP CLI focused on filename encoding control for cross-locale workflows.

It is designed for cases like:

• Archive created on a zh_CN Windows machine with WinRAR.
• Archive extracted on an en_US UTF-8 machine.
• Non-ASCII paths (CJK) become garbled without explicit encoding control.

xzip defaults to utf-8 when --encoding is omitted, and you can still override it with -e/--encoding for cross-locale archives.

Install

cargo install --locked xzip

Man pages

Man pages are generated from the clap CLI definition via clap_mangen:

make man
# produces man/xzip.1, man/xzip-pack.1, man/xzip-unpack.1, man/xzip-list.1

man -l man/xzip.1
man -l man/xzip-pack.1

Install man pages system-wide (requires root for /usr/local):

sudo make install-man
man xzip

Usage

# Pack a directory with explicit filename encoding
xzip pack -i ./my-dir -o ./my-dir.zip -e gbk -r

# List archive contents before extracting
xzip list -i ./my-dir.zip -e gbk
xzip ls -i ./my-dir.zip

# Unpack with explicit filename encoding
xzip unpack -i ./my-dir.zip -o ./out -e gbk

# Show per-file progress and elapsed time
xzip unpack -v -i ./my-dir.zip -o ./out -e gbk
xzip pack -v -i ./my-dir -o ./my-dir.zip -r

# Omit encoding (defaults to utf-8)
xzip pack -i ./my-dir -o ./my-dir.zip -r

List

list (alias ls) prints an unzip -l style table to stdout:

xzip list -i ./archive.zip -e gbk

Example output:

  Length      Date    Time    Name
---------  ---------- -----   ----
     1234  2026-07-09 09:00   aa/file.txt
        0  2026-07-09 09:00   aa/subdir/
---------                     -------
     1234                         2 files

Use the same --include / --exclude globs as unpack to preview a filtered subset.

Verbose output

-v and -vv are global flags (repeatable). Progress messages go to stderr; list tables stay on stdout.

pack and unpack are silent by default. Use -v when you want per-file progress and a final timing summary.

Common options

• -r, --recursive (pack only): include nested files/directories.
• --include <GLOB>: only process matching paths. Repeatable.
• --exclude <GLOB>: skip matching paths. Repeatable.

Example:

xzip pack -i ./project -o ./project.zip -e utf-8 -r \
  --exclude ".git/**" \
  --exclude "target/**" \
  --include "**/*.rs"

Supported encodings

• utf-8 (utf8, unicode)
• gbk (cp936, 936)
• shift_jis (shift-jis, sjis, cp932)

Why explicit encoding

Many archive tools infer filename encoding from locale or ZIP flags. In mixed environments this can produce corrupted paths during extraction. xzip makes the encoding choice explicit at runtime.