xzip 0.2.0

ZIP CLI with explicit filename encoding for pack and unpack workflows.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

# 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

```bash
cargo install --locked xzip
```

### Man pages

Man pages are generated from the clap CLI definition via [`clap_mangen`](https://docs.rs/clap_mangen):

```bash
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`):

```bash
sudo make install-man
man xzip
```

## Usage

```bash
# 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:

```bash
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.

| Level | pack | unpack | list |
|-------|------|--------|------|
| default | silent | silent | table |
| `-v` | `adding: path` + summary | `extracting: path` + summary | table + Compressed column |
| `-vv` | bytes + compression method | `uncompressed -> compressed` bytes | table + Method column |

`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:

```bash
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.