---
name: git-cliff-install
description: Проверяет наличие утилиты git-cliff и при необходимости скачивает подходящую под текущую платформу версию в ./tools/git-cliff. Нужна навыку changelog-generate.
---

# Навык: Установка утилиты git-cliff (git-cliff-install)

## Назначение

Скрипт [scripts/git-cliff-install.os](scripts/git-cliff-install.os) обеспечивает
наличие утилиты `git-cliff` — генератора журнала изменений из истории коммитов,
необходимого навыку `changelog-generate`. Скрипт проверяет, установлена ли
утилита, и при её отсутствии скачивает последний релиз проекта
[orhun/git-cliff](https://github.com/orhun/git-cliff/releases), подходящий под
текущую ОС и архитектуру, и распаковывает его в `./tools/git-cliff`.

Особенность семейства: это один из навыков проекта, обращающихся в интернет за
сторонним бинарником (наряду с `sqlcmd-install` и `bsl-ls-install`). Берётся
архив, а не системный пакет `.deb` / `.rpm`: распаковка не требует прав
администратора и не меняет систему за пределами каталога проекта.

## Когда применять

- Навык `changelog-generate` сообщил, что утилита `git-cliff` не найдена.
- Первичная настройка окружения на новой машине или CI-раннере.
- Пользователь просит установить или обновить git-cliff.
- Вызвана команда `/git-cliff-install`.

НЕ применять для генерации журнала изменений — это навык `changelog-generate`.
Этот навык только устанавливает инструмент.

## Обязательный диалог перед запуском скрипта

Параметры не требуются: платформа и версия релиза определяются автоматически.
Спрашивать ничего не нужно. Стоит предупредить пользователя, что операция
обращается в сеть (GitHub) и скачивает несколько мегабайт.

## Запуск

Из корня репозитория (предпочтительно через PowerShell — корректная кириллица
в выводе):

```
oscript .claude/skills/git-cliff-install/scripts/git-cliff-install.os
```

Необязательный аргумент:

- `--force` — переустановить, даже если git-cliff уже найден (например, чтобы
  обновиться до свежего релиза).

## Что делает скрипт (по шагам)

1. Определяет корень репозитория (`git rev-parse --show-toplevel`).
2. Ищет git-cliff: сначала локальную копию `./tools/git-cliff/git-cliff(.exe)`,
   затем утилиту в PATH. Если найдена и не указан `--force` — сообщает версию
   и завершается с кодом 0 (навык идемпотентен).
3. Определяет ОС и архитектуру и выбирает платформенный триплет:
   `x86_64-pc-windows-msvc`, `x86_64-unknown-linux-gnu`,
   `aarch64-apple-darwin` и т. п.
4. Запрашивает последний релиз через GitHub API и находит ссылку на нужный
   ассет.
5. Скачивает архив во временный каталог и распаковывает в `./tools/git-cliff`
   (ZIP — штатными средствами OneScript, `.tar.gz` — утилитой `tar`, затем
   `chmod +x`).
6. Проверяет работоспособность: запускает `git-cliff --version` и печатает
   версию.

## Почему ассет ищется по триплету, а не по точному имени

Имена ассетов git-cliff **содержат номер версии**
(`git-cliff-2.13.1-x86_64-pc-windows-msvc.zip`), поэтому предсказать имя файла
заранее нельзя. Скрипт ищет ассет, имя которого **заканчивается** на
`<триплет><расширение>`.

Проверка именно окончания принципиальна: рядом с каждым архивом в релизе лежат
файлы `.tar.gz.sha512` и `.tar.gz.sig` с тем же триплетом в имени — поиск по
вхождению подстроки выбрал бы файл подписи вместо архива.

Для платформ, где в релизе несколько вариантов, выбор зафиксирован: Windows —
`msvc` (не `gnu`), Linux — `gnu` (не `musl`).

## Интерпретация результатов

- **Exit code 0** — git-cliff доступен (был установлен ранее либо установлен
  сейчас). Сообщить пользователю расположение и версию; можно переходить к
  `changelog-generate`.
- **Exit code 1, ошибка сети / GitHub API** — показать сообщение скрипта.
  Типичные причины: нет доступа в интернет, корпоративный прокси, код 403
  из-за исчерпанного лимита анонимных запросов к GitHub API. Предложить
  повторить позже либо скачать релиз вручную и положить исполняемый файл в
  `./tools/git-cliff`.
- **Exit code 1, платформа не определена** — сборки для текущей ОС или
  архитектуры нет в релизе; предложить ручную установку.
- **Exit code 1, ассет не найден в релизе** — изменился состав релиза
  git-cliff; проверить список файлов на странице релизов и при необходимости
  скорректировать скрипт.
- **Exit code 1, утилита не запускается после распаковки** — проверить права
  на файл и совместимость сборки с платформой.

## Ограничения

- Требует доступа в интернет к `api.github.com` и `github.com`.
- Ставит утилиту ТОЛЬКО в каталог проекта (`./tools/git-cliff`), не в систему
  и не в PATH; каталог добавлен в `.gitignore` и не коммитится.
- Всегда ставит последний релиз — закрепление конкретной версии не
  предусмотрено.
- Для Linux/macOS требуется `tar` в PATH (входит в состав этих ОС).
- Не генерирует журнал изменений и не читает `cliff.toml` — это забота навыка
  `changelog-generate`.

## Состояние проверки

Проверено на живом окружении 05.08.2026 (Windows, `x86_64`): установка
end-to-end (git-cliff 2.13.1), повторный запуск (идемпотентность, код 0),
отбор ассета среди файлов `.sha512` и `.sig`.

**Не проверялось:** установка на Linux и macOS (ветка `tar -xzf` с
`--strip-components=1`), поведение при исчерпанном лимите GitHub API.