nordisk/znippy

The compress engine — for idiots

Class: idiot. Every step, nothing assumed. Goal: compress a folder into a .znippy archive and list it, from a cold shell to a finished file. If you already know Rust and the CLI, read compress-guide.md instead — this one spells out every keystroke.

What you need first

• A terminal (the black window where you type commands).
• The znippy repo on disk.

In the terminal, type this and press Enter to go into the repo:

cd /run/media/rickard/T9/git/znippy

Step 1 — build the tool

Type this and press Enter. It compiles the znippy command-line program. The first build takes a while; that is normal.

cargo xtask build --suite ORIGINAL --atom znippy

When it finishes, the program lives at ./target/release/znippy. The --release part means "build the fast version" (without it you get a slower debug build).

Step 2 — make a folder to compress

You need something to pack. Make a small test folder with two files in it — type each line and press Enter after each:

mkdir testdir
echo "hello one" > testdir/a.txt
echo "hello two" > testdir/b.txt

Now testdir is a folder with two text files. That is what we will compress.

Step 3 — compress the folder

Type this and press Enter:

./target/release/znippy compress -i testdir -o test.znippy

What each part means:

• compress — the thing we want znippy to do.
• -i testdir — the input: the folder to pack.
• -o test.znippy — the output: the archive file to create.

When it finishes you will have a new file called test.znippy in the current folder. That single file holds both of your text files, compressed and indexed.

Step 4 — look inside the archive

Type this and press Enter:

./target/release/znippy list test.znippy

This prints every file stored in the archive. You should see a.txt and b.txt. If you do, it worked — the archive is real and readable.

Optional flags (only if you need them)

You do not need these for the steps above, but here is what they do if you see them:

• --no-skip — compress everything. Normally znippy skips already-compressed files (like .png or .gz) and stores them as-is because squeezing them again just wastes time. This flag forces it to try anyway.
• --format rust (or python, or maven) — tells znippy the project is a Rust/Python/Maven tree so it packs it in an ecosystem-aware way.
• --meta-format iceberg --warehouse DIR — writes the archive's index into an Iceberg warehouse folder instead of inside the .znippy file. Advanced; ignore it to start.
• --sign KEY --sign-cert CERT --sign-alg p256 — cryptographically signs the archive so others can verify you made it. Ignore it to start.

That's it

You built the tool, made a folder, compressed it into one .znippy file, and listed its contents. To compress a real folder, repeat Step 3 with your own folder after -i and your own output name after -o.