foresle/knyga
1
0
Fork 0
Code Issues Activity
A CLI app that re-links your PocketBook notes to a book after you've re-tagged its metadata
13 commits 1 branch 0 tags 69 KiB
  • Rust 100%
Find a file
Exact
Orest Smertnyi (foresle) 206ff4a515
 Add the repository link to Cargo.toml
2026-04-25 16:48:51 +02:00
src Add completions 2026-04-25 15:11:52 +02:00
tests Add final function to update digests in databases 2026-04-25 13:10:59 +02:00
.gitignore Add reverse engineered compute digest function with Book struct 2026-04-19 22:28:49 +02:00
Cargo.lock Add completions 2026-04-25 15:11:52 +02:00
Cargo.toml Add the repository link to Cargo.toml 2026-04-25 16:48:51 +02:00
LICENSE Update readme description 2026-04-25 14:14:07 +02:00
README.md Add link to video demonstration 2026-04-25 15:45:46 +02:00

README.md

knyga

A CLI app that re-links your PocketBook notes to a book after you've re-tagged its metadata.

The problem

PocketBook identifies books in its library by file hash, not ISBN or any stable ID. Touch the EPUB's metadata (fix a typo in the author, swap the cover, normalize the title) and the hash changes. The device now sees a brand-new book and silently orphans every highlight, bookmark, and note you ever made on it. Your annotations still live in the device's databases, but they point at a hash that no longer matches anything on disk. Dead references.

Subjectively, hashing the whole file as a book identity is a questionable design choice. Objectively, it's what ships, and we have to work around it.

The fix

The app rewrites the stale hash inside PocketBook's on-device databases so your notes reattach to the re-tagged file. No re-reading, no manually re-creating highlights, no losing progress.

Demo

A walkthrough of the tool in action: on peertube.in.ua.

Recommended companion tools

When you edit an EPUB's metadata, use tools that respect the spec.

  • Sigil — open-source EPUB2/EPUB3 editor. Preserves OPF/NCX/Nav structure as-is and ships with built-in EPUBCheck validation.
  • EPUBCheck — the official W3C validator. Run epubcheck book.epub after any edit to confirm the file is still spec-compliant before copying it back to the device.

Shell completions (fish)

Generate the completion script and drop it in fish's completions directory:

knyga completions fish > ~/.config/fish/completions/knyga.fish

A note on authorship

This README was written partly with the help of an LLM, and the reverse engineering of PocketBook's database format also partly involved an LLM. The code itself, however, was written by hand by a human.