.nornir/for-idiots.md

znippy — for idiots (f0, zero to a packed-and-pulled archive)

Class: idiot. Every step, nothing assumed. Goal: from a cold shell, pack a folder into a znippy archive, list it, and pull one file back out. If you already know Rust and a terminal, read 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. Type this and press Enter:

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

Step 1 — build the `znippy` program

Type this and press Enter. The first time it will take a few minutes; that is normal.

cargo xtask build --suite ORIGINAL --atom znippy

When it finishes, the program exists at target/release/znippy. Check it with:

./target/release/znippy --help

You should see a list of commands (compress, decompress, list, get, verify, …). If you see "command not found", you are in the wrong folder — repeat the cd from above.

Step 2 — make a folder to pack

Let's create a tiny folder with two files so you can see it work. Type each line, Enter after each:

mkdir -p demo
echo "hello from znippy" > demo/hello.txt
echo "second file" > demo/notes.txt

Step 3 — pack the folder into an archive

Type this and press Enter:

./target/release/znippy compress -i demo -o demo.znippy

-i demo is the input folder.
-o demo.znippy is the output archive it will create.

When it returns to the prompt with no red error text, you have an archive. Confirm the file is there:

ls -la demo.znippy

Step 4 — list what is inside

Type this and press Enter:

./target/release/znippy list demo.znippy

You should see hello.txt and notes.txt listed. This read the archive's index only — it did not unpack anything.

Step 5 — pull ONE file back out

This is the party trick: get a single file without unpacking the rest. Type and press Enter:

./target/release/znippy get -i demo.znippy -p hello.txt -o hello-back.txt

-p hello.txt is the path inside the archive.
-o hello-back.txt is where to write it.

Now look at it:

cat hello-back.txt

It should print hello from znippy. If you leave off -o, the bytes print straight to the screen instead:

./target/release/znippy get -i demo.znippy -p notes.txt

Step 6 — unpack everything and check it

To restore the whole folder somewhere new, and confirm nothing is corrupted:

./target/release/znippy decompress -i demo.znippy -o demo-restored
./target/release/znippy verify -i demo.znippy

verify recomputes a checksum for every chunk and complains loudly if even one byte changed. ok (no red text) means the archive is intact.

What just happened

You packed a folder across all your CPU cores, then pulled one file back out by name — the whole point of znippy. To go deeper (compress a real package tree, query the index with DuckDB, sign an archive), read guide.md. To pack a big directory of .jar/.crate files, the same compress command works — znippy stores already-compressed files as-is at full speed.