Посібник — ketch docs

Як ketch зберігає, відстежує та лінкує те, що встановлює. Кожна команда з прикладом — у COMMANDS.md.

Сховище та відкат

Усе лежить у ~/.ketch: версіоновані дані в store/, посилання в bin/, state.json із записом того, що встановлено, і stats.db із записом того, що відбувалося. За межами цього дерева нічого не пишеться, окрім .app-бандлів, яким місце в /Applications, користувацьких каталогів man-сторінок і автодоповнень, про які повідомляє ketch doctor, файлу запуску оболонки, який ketch path install редагує на ваше прохання, ./ketch.lock і ./ketch.toml, коли ви їх запитуєте, та самого запущеного бінарника, коли ketch self upgrade замінює його на місці поза сховищем.

Оновлення залишає попередній префікс на диску і записує його в retained у state.json разом із політикою retention (keep, за замовчуванням 1). ketch rollback <pkg> перелінковує цей префікс — він ніколи не завантажує повторно. ketch prune — єдина команда, що видаляє збережені префікси; вона залишає keep попередніх версій. ketch list і ketch info показують, що ще збережено. Файли стану, записані до появи цього поля, і далі завантажуються: відсутній retention означає keep 1, відсутній retained — нічого.

Встановлення з диска

ketch install --path PATH (або ketch install local:PATH) встановлює те, що вже є на цій машині: голий бінарник, символічне посилання на нього, архів або .app-бандл. Шлях записується в абсолютній формі, оригінал ніколи не змінюється, а видалення прибирає лише копію ketch. Одиночний файл лінкується під іменем пакета, яке береться з імені файлу, якщо --name не каже інакше:

ketch install --path ./target/release/mytool --name mytool

Локальний пакет не має релізів: він записує версію 0.0.0-local, outdated і upgrade його пропускають, а повторне встановлення того самого шляху з --force підхоплює перезібраний файл. Опублікованої контрольної суми немає, тож require_checksums до нього не застосовується. ketch lock записує хеш того, що там було, і sync відмовляється від шляху, якщо його вміст відтоді змінився.

--name працює для будь-якого одиночного пакета, не лише локального, а upgrade і sync зберігають вибране ним ім'я.

Що у вас було і коли

ketch history              # кожне встановлення, оновлення та видалення, нові зверху
ketch history rg           # лише версії цього пакета, включно зі старими
ketch stats                # скільки встановлень і скільки вони тривають

state.json каже, що встановлено зараз, і переписується за кожної зміни, тож не може відповісти, яка версія була у вас у березні. stats.db — друга половина: журнал лише на дозапис, що переживає самі пакети, тому ketch history rg працює й після ketch uninstall rg. Видаліть файл — втратите історію, але не пакети.

Що змінилося

ketch changelog rg            # запис для вашої версії
ketch changelog rg --latest   # реліз, який ви отримаєте під час оновлення
ketch changelog rg --release  # нотатки до релізу, а не файл у поставці

Більшість релізів несуть історію двічі: CHANGELOG.md всередині архіву та нотатки, прикріплені до релізу. ketch надає перевагу файлу — він уже на диску, тож це працює без мережі — і переходить до нотаток, коли у файлі немає запису для цієї версії; так стається щоразу, коли проєкт ставить тег раніше, ніж пише заголовок.

Changelog іде в stdout, а все інше в stderr, тому ketch changelog rg > NOTES.md залишає лише markdown.

Встановлення кількох одразу

ketch install rg fd bat jq      # чотири завантаження одночасно, чотири індикатори
ketch install rg fd --jobs 1    # по одному

Завантаження за замовчуванням ідуть паралельно і здебільшого чекають, тож набір утиліт займає приблизно стільки, скільки найповільніша, а не суму всіх. Перетинаються лише завантаження та розпакування: пакети потрапляють у сховище по одному, у тому порядку, в якому завершуються завантаження, — не обов'язково в тому, в якому ви їх просили. Код виходу та виведені результати все одно йдуть у порядку запиту.

upgrade і sync працюють так само. --jobs N задає ширину для будь-якої з них; jobs у файлі конфігурації задає значення за замовчуванням.

Журнал

Кожен запуск пишеться в ~/.ketch/logs/ketch.log — включно з рядками, які проковтнув --quiet, і налагоджувальними подробицями, які показав би --verbose. Невдала команда повідомляє, де його знайти.

2026-08-27T09:12:33Z [4218] INFO  ketch 0.1.0 · install rg fd
2026-08-27T09:12:34Z [4218] ERROR HTTP 404 from https://api.github.com/...

Встановіть log_format = "json" для JSON Lines, log_level у debug для всього або off для нічого. Файл ротується в ketch.log.1 при 5 МіБ, тож чистити його вручну не потрібно. ketch doctor показує, де він лежить і наскільки виріс.

Відтворення машини

ketch lock            # записати ./ketch.lock з того, що встановлено
ketch lock --check    # щось розійшлося?
ketch sync            # привести цю машину до lock-файлу

Закомітьте ketch.lock поруч із dotfiles, і нова машина відстає від старої на одну команду. Скрізь відтворюється тег; записана контрольна сума перевіряється на машині тієї ж цілі, а в інших випадках ketch вибирає відповідний асет і перевіряє його за джерелом. --prune видаляє те, чого немає в lock-файлі, --dry-run спершу показує план. Див. LOCKFILE.md.

Додавання до PATH

ketch path              # показати налаштування PATH (те саме, що `path status`)
ketch path status       # які оболонки налаштовані і де
ketch path install      # відредагувати ті, якими ви користуєтеся
ketch path uninstall    # прибрати блок назад

У Unix він знаходить bash, zsh і fish — оболонку з $SHELL і будь-яку, чий файл запуску у вас уже є, — і пише один блок між маркерами, щоб переписати його, якщо корінь переїде, і чисто видалити пізніше. У Windows він пише користувацький PATH, який читає кожен новий термінал. --shell <name> вибирає Unix-оболонку, --all бере всі відомі ketch цілі, --dry-run показує правку без її застосування, а --print дає рядок, щоб вставити його туди, про що ketch не знає.

Рядок, доданий вами самостійно, ketch не чіпає і не дублює. ketch doctor повідомляє про PATH як про помилку, коли жодна оболонка про нього не знає, як про попередження, коли файл запуску його містить, але поточна оболонка запущена до правки, а ketch doctor --fix виконує налаштування за вас.

Як знаходиться пакет

Ім'я розв'язується за чотирма рівнями по черзі:

ваші власні маніфести в ~/.ketch/manifests/
завантажений реєстр пакетів — див. REGISTRY.md
реєстр, вбудований у бінарник, щоб поширені утиліти працювали офлайн
виведення з owner/repo — саме воно дає змогу встановити некурований репозиторій узагалі без маніфесту

Виведення вибирає асет релізу, що пасує вашій машині — архітектурі, ОС і libc, — і пояснює вибір у ketch info --assets.

Якщо воно помиляється, маніфест каже, що робити натомість: який асет, які бінарники і під якими іменами. Див. MANIFESTS.md.

Джерела, окрім GitHub, додаються плагінами — один виконуваний файл, без нового релізу ketch. Див. PLUGINS.md.

Підтримка платформ

macOS, Linux і Windows. Кожна ОС має бекенд Platform, який вибирає асет релізу, розпаковує його і розміщує бінарники; усе, що вище цього трейту, спільне. cargo test запускає набір для ОС хоста; CI робить це на macOS, Linux і Windows. Способи встановлення: curl | bash через install.sh на macOS і Linux, irm | iex через install.ps1 на Windows або brew install --cask pyrlyn/tap/ketch на macOS. ketch path install додає ~/.ketch/bin до PATH (файли запуску оболонки в Unix; користувацький PATH у Windows). Релізи публікують архів для кожної цілі; install.sh і install.ps1 завантажують той, що пасує машині, на якій вони запущені. Homebrew tap — pyrlyn/homebrew-tap; реєстр пакетів — pyrlyn/ketch-registry.