Skip to content

USAGE.md

Latest commit

 

History

History
761 lines (553 loc) · 58.6 KB

USAGE.md

File metadata and controls

761 lines (553 loc) · 58.6 KB

Использование командной строки gac

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | हिन्दी | Tiếng Việt | Français | Русский | Español | Português | Norsk | Svenska | Deutsch | Nederlands | Italiano

Этот документ описывает все доступные флаги и опции для CLI-инструмента uvx gac.

Содержание

Базовое использование

uvx gac init
# Затем следуйте подсказкам для настройки вашего поставщика, модели и API-ключей в интерактивном режиме
uvx gac

Генерирует сообщение коммита на основе LLM для индексированных изменений и запрашивает подтверждение. Подтверждение принимает:

  • y или yes - Продолжить коммит
  • n или no - Отменить коммит
  • r или reroll - Пересгенерировать сообщение коммита с тем же контекстом
  • e или edit - Редактировать сообщение коммита. По умолчанию открывает встроенную TUI с горячими клавишами vi/emacs. Установите GAC_EDITOR, чтобы открыть предпочитаемый редактор (напр., GAC_EDITOR=code gac для VS Code, GAC_EDITOR=vim gac для vim)
  • Любой другой текст - Пересгенерировать с этим текстом в качестве обратной связи (например, сделай короче, сфокусируйся на производительности)
  • Пустой ввод (только Enter) - Показать подсказку снова

Флаги основного рабочего процесса

Флаг / Опция Короткий Описание
--add-all -a Индексировать все изменения перед коммитом
--stage -S Интерактивно выбрать файлы для индексации с древовидным TUI
--group -g Группировать индексированные изменения в несколько логических коммитов
--push -p Отправить изменения в удалённый репозиторий после коммита
--yes -y Автоматически подтверждать коммит без запроса
--dry-run Показать, что произойдёт, не внося никаких изменений
--message-only Вывести только сгенерированное сообщение коммита без фактического выполнения коммита
--no-verify Пропускать хуки pre-commit и lefthook при коммите
--skip-secret-scan Пропускать сканирование безопасности на наличие секретов в индексированных изменениях
--no-verify-ssl Пропускать проверку SSL-сертификата (полезно для корпоративных прокси)
--signoff Добавить строку Signed-off-by в сообщение коммита (соответствие DCO)
--interactive -i Задавать вопросы об изменениях для лучших коммитов

Примечание: --stage и --add-all взаимоисключающие. Используйте --stage для интерактивного выбора файлов для индексации, и --add-all для индексации всех изменений сразу.

Примечание: Комбинируйте -a и -g (то есть -ag) для индексации ВСЕХ изменений, затем группировки их в коммиты.

Примечание: При использовании --group лимит максимальных выходных токенов автоматически масштабируется в зависимости от количества фиксируемых файлов (2x для 1-9 файлов, 3x для 10-19 файлов, 4x для 20-29 файлов, 5x для 30+ файлов). Это гарантирует, что у LLM достаточно токенов для генерации всех сгруппированных коммитов без усечения, даже для больших наборов изменений.

Примечание: --message-only и --group являются взаимоисключающими. Используйте --message-only, когда вам нужно получить сообщение коммита для внешней обработки, и --group, когда вы хотите организовать несколько коммитов в рамках текущего git‑рабочего процесса.

Примечание: Флаг --interactive предоставляет дополнительный контекст LLM, задавая вопросы о ваших изменениях, что приводит к более точным и детальным сообщениям коммитов. Это особенно полезно для сложных изменений или когда вы хотите убедиться, что сообщение коммита полностью отражает контекст вашей работы.

Настройка сообщений

Флаг / Опция Короткий Описание
--one-liner -o Генерировать однострочное сообщение коммита
--verbose -v Генерировать подробные сообщения коммита с мотивацией, архитектурой и влиянием
--hint <text> -h Добавить подсказку для направления LLM
--model <model> -m Указать модель для использования в этом коммите
--language <lang> -l Переопределить язык (название или код: 'Spanish', 'es', 'zh-CN', 'ja')
--scope -s Выводить соответствующую область для коммита
--50-72 Применять правило 50/72 для форматирования сообщений коммита

Примечание: Флаг --50-72 применяет правило 50/72, где:

  • Строка темы: максимум 50 символов
  • Строки тела: максимум 72 символа на строку
  • Это сохраняет сообщения коммита читаемыми в git log --oneline и интерфейсе GitHub

Вы также можете установить GAC_USE_50_72_RULE=true в файле .gac.env, чтобы всегда применять это правило.

Примечание: Вы можете предоставлять обратную связь интерактивно, просто вводя её в подсказке подтверждения - нет необходимости добавлять префикс 'r'. Введите r для простого пересоздания, e для редактирования сообщения (встроенная TUI по умолчанию, или $GAC_EDITOR если установлен), или введите свою обратную связь напрямую, например сделай короче.

Вывод и детализация

Флаг / Опция Короткий Описание
--quiet -q Подавить весь вывод, кроме ошибок
--log-level <level> Установить уровень логирования (debug, info, warning, error)
--show-prompt Показать LLM-подсказку, используемую для генерации сообщения коммита

Справка и версия

Флаг / Опция Короткий Описание
--version Показать версию gac и выйти
--help Показать справочное сообщение и выйти

Примеры рабочих процессов

  • Индексировать все изменения и закоммитить:

    uvx gac -a

  • Закоммитить и отправить за один шаг:

    uvx gac -ap

  • Сгенерировать однострочное сообщение коммита:

    uvx gac -o

  • Сгенерировать подробное сообщение коммита со структурированными разделами:

    uvx gac -v

  • Добавить подсказку для LLM:

    uvx gac -h "Рефакторинг логики аутентификации"

  • Вывести область для коммита:

    uvx gac -s

  • Группировать индексированные изменения в логические коммиты:

    uvx gac -g
# Группирует только файлы, которые вы уже проиндексировали

  • Группировать все изменения (индексированные + неиндексированные) и автоматически подтвердить:

    uvx gac -agy
# Индексирует всё, группирует и автоматически подтверждает

  • Использовать конкретную модель только для этого коммита:

    uvx gac -m anthropic:claude-haiku-4-5

  • Сгенерировать сообщение коммита на конкретном языке:

    # Используя языковые коды (короче)
uvx gac -l zh-CN
uvx gac -l ja
uvx gac -l es

# Используя полные названия
uvx gac -l "Simplified Chinese"
uvx gac -l Japanese
uvx gac -l Spanish

  • Тестовый запуск (увидеть, что произойдёт):

    uvx gac --dry-run

  • Получить только сообщение коммита (для интеграции со скриптами):

    uvx gac --message-only
# Пример вывода: feat: add user authentication system

  • Получить сообщение коммита в однострочном формате:

    uvx gac --message-only --one-liner
# Пример вывода: feat: add user authentication system

  • Использовать интерактивный режим для предоставления контекста:

    uvx gac -i
# Какова основная цель этих изменений?
# Какую проблему вы решаете?
# Есть ли детали реализации, которые стоит упомянуть?

  • Интерактивный режим с детальным выводом:

    uvx gac -i -v
# Задавать вопросы и генерировать детальные сообщения коммитов

Расширенные возможности

  • Комбинируйте флаги для более мощных рабочих процессов (например, uvx gac -ayp для индексации, автоматического подтверждения и отправки)
  • Используйте --show-prompt для отладки или просмотра подсказки, отправленной в LLM
  • Настраивайте детализацию с помощью --log-level или --quiet
  • Используйте --message-only для интеграции со скриптами и автоматизированных рабочих процессов

Интеграция со скриптами и внешняя обработка

Флаг --message-only разработан для интеграции со скриптами и рабочих процессов с внешними инструментами. Он выводит только исходное сообщение коммита без какого-либо форматирования, индикаторов загрузки или дополнительных элементов интерфейса.

Варианты использования:

  • Интеграция с AI-агентами: Позволяет AI-агентам получать сообщения коммитов и обрабатывать коммиты самостоятельно
  • Альтернативные VCS: Использование сгенерированных сообщений с другими системами контроля версий (Mercurial, Jujutsu и т.д.)
  • Пользовательские рабочие процессы коммитов: Обработка или изменение сообщения перед коммитом
  • CI/CD конвейеры: Извлечение сообщений коммитов для автоматизированных процессов

Пример использования в скриптах:

#!/bin/bash
# Получение сообщения коммита и использование с пользовательской функцией коммита
MESSAGE=20 20 12 61 79 80 81 98 701 33 100 204 250 395 398 399 400uvx gac --message-only --add-all --yes)
git commit -m "$MESSAGE"
# Пример интеграции с Python
import subprocess

def get_commit_message():
    result = subprocess.run(
        ["gac", "--message-only", "--yes"],
        capture_output=True, text=True
    )
    return result.stdout.strip()

message = get_commit_message()
print(f"Сгенерированное сообщение: {message}")

Ключевые возможности для использования в скриптах:

  • Чистый вывод без форматирования Rich или индикаторов загрузки
  • Автоматический обход запросов подтверждения
  • Фактический коммит в git не выполняется
  • Работает с --one-liner для упрощенного вывода
  • Может комбинироваться с другими флагами, такими как --hint, --model и т.д.

Пропуск хуков pre-commit и lefthook

Флаг --no-verify позволяет вам пропустить любые хуки pre-commit или lefthook, настроенные в вашем проекте:

uvx gac --no-verify  # Пропустить все хуки pre-commit и lefthook

Используйте --no-verify, когда:

  • Хуки pre-commit или lefthook временно не работают
  • Работа с трудоёмкими хуками
  • Коммит кода в разработке, который ещё не проходит все проверки

Примечание: Используйте с осторожностью, так как эти хуки поддерживают стандарты качества кода.

Сканирование безопасности

uvx gac включает встроенное сканирование безопасности, которое автоматически обнаруживает потенциальные секреты и API-ключи в ваших индексированных изменениях перед выполнением любых вызовов AI API. Если секрет обнаружен, рабочий процесс немедленно прерывается — вызов API не происходит. Это гарантирует, что ваши конфиденциальные данные никогда не отправляются в модель ИИ. Сканер использует сопоставление шаблонов на основе регулярных выражений, а не LLM, поэтому сканирование быстрое и полностью локальное.

Пропуск сканирования безопасности:

uvx gac --skip-secret-scan  # Пропустить сканирование безопасности для этого коммита

Для отключения навсегда: Установите GAC_SKIP_SECRET_SCAN=true в вашем файле .gac.env.

Когда пропускать:

  • Коммит примеров кода с заглушками для ключей
  • Работа с тестовыми фикстурами, содержащими фиктивные учётные данные
  • Когда вы проверили, что изменения безопасны

Примечание: Сканер использует сопоставление шаблонов на основе регулярных выражений (не LLM) для обнаружения распространённых форматов секретов. Он выполняется перед любым вызовом AI API — если секрет найден, вызов API не происходит. Всегда просматривайте ваши индексированные изменения перед коммитом.

Binary File Detection

uvx gac includes automatic detection of binary files in staged changes, preventing accidental commits of compiled files, images, and other binary assets that typically should not be in version control. The detector uses multiple strategies:

  • Extension-based detection - Fast recognition of 60+ binary file types
  • Null byte detection - Reliable indicator of binary content
  • UTF-8 validity checking - Text files should be valid UTF-8 or ASCII
  • Magic byte identification - Detects file types from file signatures

Supported binary types:

  • Executables: .exe, .dll, .so, .dylib, .bin, .o, .obj, .lib, .a
  • Archives: .zip, .tar, .gz, .bz2, .7z, .rar, .xz, .zst
  • Images: .png, .jpg, .jpeg, .gif, .bmp, .ico, .svg, .tiff, .webp
  • Media: .mp3, .wav, .ogg, .flac, .m4a, .aac, .mp4, .avi, .mkv, .mov, .wmv
  • Fonts: .ttf, .otf, .woff, .woff2, .eot
  • Documents: .pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx
  • Databases: .db, .sqlite, .sqlite3, .mdb, .accdb
  • Compiled code: .class, .jar, .war, .ear, .pyc, .pyd, .pyo, .beam, .hi

When binary files are detected:

uvx gac
# Output:
# BINARY FILE WARNING: Binary files detected!
#
#   • image.png
#     Type: Image file
#     Size: 2.3 MB
#
# Binary files should typically be excluded from version control.
# Use .gitignore to prevent accidental commits of binary files.
#
# Options:
#   [a] Abort commit (recommended)
#   [c] Continue anyway (you know what you are doing)
#   [r] Unstage binary file(s) and continue
#
# Choose an option [a]:

Best practices:

  1. Add binary patterns to .gitignore:

    # Compiled files
*.exe
*.dll
*.so
*.dylib
*.o
*.a

# Images
*.png
*.jpg
*.jpeg
*.gif

# Archives
*.zip
*.tar.gz

# Python
*.pyc
__pycache__/

  2. Use Git LFS for large binary files that must be tracked:

    git lfs track "*.psd"
git lfs track "*.zip"

  3. Commit binary files only when necessary:

    • Icons and assets that are part of the codebase
    • Test fixtures that need to be versioned
    • Documentation images

Note: Binary detection runs automatically during the commit workflow (similar to secret scanning). There is no flag to disable it, as binary files generally should not be committed unless there is a specific reason. If you need to commit a binary file, choose the "Continue anyway" option or ensure it is properly documented in your project guidelines.

Проверка SSL-сертификата

Флаг --no-verify-ssl позволяет пропустить проверку SSL-сертификата для API-запросов:

uvx gac --no-verify-ssl  # Пропустить проверку SSL для этого коммита

Для постоянной настройки: Установите GAC_NO_VERIFY_SSL=true в вашем файле .gac.env.

Используйте --no-verify-ssl, когда:

  • Корпоративные прокси перехватывают SSL-трафик (MITM-прокси)
  • Среда разработки использует самоподписанные сертификаты
  • Возникают ошибки SSL-сертификата из-за настроек сетевой безопасности

Примечание: Используйте эту опцию только в доверенных сетевых средах. Отключение проверки SSL снижает безопасность и может сделать ваши API-запросы уязвимыми для атак «человек посередине».

Строка Signed-off-by (соответствие DCO)

uvx gac поддерживает добавление строки Signed-off-by в сообщения коммитов, что требуется для соответствия Developer Certificate of Origin (DCO) во многих проектах с открытым исходным кодом.

Добавить signoff :

uvx gac --signoff  # Добавить строку Signed-off-by в сообщение коммита (соответствие DCO)

Для постоянной настройки : Установите GAC_SIGNOFF=true в файле .gac.env или добавьте signoff=true в вашу конфигурацию.

Что делает :

  • Добавляет Signed-off-by: Ваше Имя <your.email@example.com> в сообщение коммита
  • Использует вашу конфигурацию git (user.name и user.email) для строки
  • Требуется для проектов, таких как Cherry Studio, ядро Linux и других, использующих DCO

Настройка идентификации git :

Убедитесь, что ваша конфигурация git имеет правильное имя и email :

git config --global user.name "Your Full Name"
git config --global user.email "your.email@example.com"

Примечание : Строка Signed-off-by добавляется git во время коммита, а не ИИ во время генерации сообщения. Вы не увидите её в предпросмотре, но она будет в финальном коммите (проверьте с помощью git log -1).

Замечания по конфигурации

  • Рекомендуемый способ настройки gac - запустить uvx gac init и следовать интерактивным подсказкам.
  • Уже настроили язык и нужно просто переключить поставщиков или модели? Запустите uvx gac model для повторной настройки без вопросов о языке.
  • Используете Claude Code? См. руководство по настройке Claude Code для инструкций по аутентификации OAuth.
  • Используете ChatGPT OAuth? См. руководство по настройке ChatGPT OAuth для инструкций по аутентификации через браузер.
  • Используете GitHub Copilot? См. руководство по настройке GitHub Copilot для инструкций по аутентификации Device Flow.
  • gac загружает конфигурацию в следующем порядке приоритета:
    1. Флаги CLI
    2. Уровень проекта .gac.env
    3. Уровень пользователя ~/.gac.env
    4. Переменные окружения

Расширенные опции конфигурации

Вы можете настроить поведение gac с помощью этих дополнительных переменных окружения:

  • GAC_EDITOR=code --wait - Переопределяет редактор, используемый при нажатии e в подсказке подтверждения. По умолчанию e открывает встроенную TUI; установка GAC_EDITOR переключает на внешний редактор. Поддерживает любую команду редактора с аргументами. Флаги ожидания (--wait/-w) автоматически вставляются для известных GUI-редакторов (VS Code, Cursor, Zed, Sublime Text), чтобы процесс блокировался до закрытия файла
  • GAC_ALWAYS_INCLUDE_SCOPE=true - Автоматически выводить и включать область в сообщения коммитов (например, feat(auth): вместо `feat:)
  • GAC_ALWAYS_GROUPED=true - Всегда использовать режим группированных коммитов (эквивалентно постоянной передаче флага -g или --group)
  • GAC_VERBOSE=true - Генерировать подробные сообщения коммита с разделами мотивации, архитектуры и влияния
  • GAC_USE_50_72_RULE=true - Всегда применять правило 50/72 для сообщений коммита (тема ≤50 символов, строки тела ≤72 символа)
  • GAC_SIGNOFF=true - Всегда добавлять строку Signed-off-by к коммитам (для соответствия DCO)
  • GAC_TEMPERATURE=0.7 - Управлять творческостью LLM (0.0-1.0, ниже = более сфокусированно)
  • GAC_REASONING_EFFORT=medium - Управлять глубиной рассуждения/мышления для моделей, поддерживающих расширенное мышление (low, medium, high, max). Оставьте незаданным, чтобы использовать значение по умолчанию для каждой модели. Отправляется только совместимым провайдерам (стиль OpenAI; не Anthropic).
  • GAC_MAX_OUTPUT_TOKENS=4096 - Максимальное количество токенов для сгенерированных сообщений (автоматически масштабируется 2-5x при использовании --group в зависимости от количества файлов; переопределите для большего или меньшего значения)
  • GAC_WARNING_LIMIT_TOKENS=4096 - Предупреждать, когда подсказки превышают это количество токенов
  • GAC_SYSTEM_PROMPT_PATH=/path/to/custom_prompt.txt - Использовать пользовательскую системную подсказку для генерации сообщения коммита
  • GAC_LANGUAGE=Spanish - Генерировать сообщения коммитов на конкретном языке (например, Spanish, French, Japanese, German). Поддерживает полные названия или ISO-коды (es, fr, ja, de, zh-CN). Используйте uvx gac language для интерактивного выбора
  • GAC_TRANSLATE_PREFIXES=true - Переводить префиксы обычных коммитов (feat, fix и т.д.) на целевой язык (по умолчанию: false, сохраняет префиксы на английском)
  • GAC_SKIP_SECRET_SCAN=true - Отключить автоматическое сканирование безопасности на наличие секретов в индексированных изменениях (используйте с осторожностью)
  • GAC_NO_VERIFY_SSL=true - Пропускать проверку SSL-сертификата для API-запросов (полезно для корпоративных прокси, которые перехватывают SSL-трафик)
  • GAC_DISABLE_STATS=true - Отключить отслеживание статистики использования (нет чтения или записи файла статистики; существующие данные сохраняются). Только truthy-значения отключают статистику; установка false/0/no/off оставляет статистику включённой, как и отсутствие переменной

Смотрите .gac.env.example для полного шаблона конфигурации.

Для подробного руководства по созданию пользовательских системных подсказок смотрите docs/CUSTOM_SYSTEM_PROMPTS.md.

Подкоманды конфигурации

Доступны следующие подкоманды:

  • uvx gac init — Интерактивный мастер настройки для поставщика, модели и языковой конфигурации
  • uvx gac model — Настройка поставщика/модели/API-ключа без подсказок языка (идеально для быстрого переключения)
  • uvx gac auth — Показать статус OAuth-аутентификации для всех провайдеров
  • uvx gac auth claude-code login — Войти в Claude Code используя OAuth (открывает браузер)
  • uvx gac auth claude-code logout — Выйти из Claude Code и удалить сохраненный токен
  • uvx gac auth claude-code status — Проверить статус аутентификации Claude Code
  • uvx gac auth chatgpt login — Войти в ChatGPT используя OAuth (открывает браузер)
  • uvx gac auth chatgpt logout — Выйти из ChatGPT и удалить сохраненный токен
  • uvx gac auth chatgpt status — Проверить статус аутентификации ChatGPT
  • uvx gac auth copilot login — Войти в GitHub Copilot с использованием Device Flow
  • uvx gac auth copilot login --host ghe.mycompany.com — Войти в Copilot на экземпляре GitHub Enterprise
  • uvx gac auth copilot logout — Выйти из Copilot и удалить сохранённые токены
  • uvx gac auth copilot status — Проверить статус аутентификации Copilot
  • uvx gac config show — Показать текущую конфигурацию
  • uvx gac config set KEY VALUE — Установить ключ конфигурации в $HOME/.gac.env
  • uvx gac config get KEY — Получить значение конфигурации
  • uvx gac config unset KEY — Удалить ключ конфигурации из $HOME/.gac.env
  • uvx gac language (или uvx gac lang) — Интерактивный селектор языка для сообщений коммитов (устанавливает GAC_LANGUAGE)
  • uvx gac editor (или uvx gac edit) — Интерактивный селектор редактора для клавиши e в prompt подтверждения (устанавливает GAC_EDITOR)
  • uvx gac diff — Показать отфильтрованный git diff с опциями для индексированных/неиндексированных изменений, цвета и усечения
  • uvx gac serve — Запустить GAC как MCP-сервер для интеграции с ИИ-агентами (транспорт stdio)
  • uvx gac stats show — Просмотреть статистику использования gac (итоги, серии, ежедневная и еженедельная активность, использование токенов, лучшие проекты со средним файлов, лучшие модели со скоростью и задержкой)
  • uvx gac stats models — Подробная статистика для всех моделей с разбивкой токенов, скоростью, задержкой и графиками задержки на коммит
  • uvx gac stats projects — Статистика для всех проектов с разбивкой токенов и средним файлов на gac
  • uvx gac stats recent — Последние 10 gac с токенами, скоростью, задержкой и файлами на gac (-n 20 для большего количества)
  • uvx gac stats reset — Сбросить всю статистику до нуля (запрашивает подтверждение)
  • uvx gac stats reset model <model-id> — Сбросить статистику для конкретной модели (без учёта регистра)

Интерактивный режим

Флаг --interactive (-i) улучшает генерацию сообщений коммитов gac, задавая целенаправленные вопросы о ваших изменениях. Этот дополнительный контекст помогает LLM создавать более точные, детальные и контекстуально соответствующие сообщения коммитов.

Как это работает

Когда вы используете --interactive, gac задаст вопросы, такие как:

  • Какова основная цель этих изменений? - Помогает понять высокоуровневую цель
  • Какую проблему вы решаете? - Предоставляет контекст о мотивации
  • Есть ли детали реализации, которые стоит упомянуть? - Захватывает технические спецификации
  • Есть ли breaking changes? - Идентифицирует потенциальные проблемы влияния
  • Это связано с какой-либо issue или тикетом? - Связывает с управлением проектами

Когда использовать интерактивный режим

Интерактивный режим особенно полезен для:

  • Сложных изменений, где контекст не ясен только из diff
  • Работы по рефакторингу, охватывающей несколько файлов и концепций
  • Новых функций, требующих объяснения общей цели
  • Исправления ошибок, где корневая причина не сразу видна
  • Оптимизации производительности, где логика не очевидна
  • Подготовки к code review - вопросы помогают вам подумать о своих изменениях

Примеры использования

Базовый интерактивный режим:

uvx gac -i

Это сделает следующее:

  1. Покажет сводку индексированных изменений
  2. Задаст вопросы об изменениях
  3. Сгенерирует сообщение коммита с вашими ответами
  4. Попросит подтверждения (или автоматически подтвердит при сочетании с -y)

Интерактивный режим с индексированными изменениями:

uvx gac -ai
# Индексировать все изменения, затем задать вопросы для лучшего контекста

Интерактивный режим с конкретными подсказками:

uvx gac -i -h "Миграция базы данных для профилей пользователей"
# Задавать вопросы, предоставляя конкретную подсказку для фокусировки LLM

Интерактивный режим с детальным выводом:

uvx gac -i -v
# Задавать вопросы и генерировать детальное, структурированное сообщение коммита

Автоматически подтвержденный интерактивный режим:

uvx gac -i -y
# Задавать вопросы, но автоматически подтвердить результирующий коммит

Рабочий процесс вопросов и ответов

Интерактивный рабочий процесс следует этому шаблону:

  1. Обзор изменений - gac показывает сводку того, что вы коммитите
  2. Ответ на вопросы - отвечайте на каждый запрос с релевантными деталями
  3. Улучшение контекста - ваши ответы добавляются к LLM-промпту
  4. Генерация сообщения - LLM создает сообщение коммита с полным контекстом
  5. Подтверждение - проверьте и подтвердите коммит (или автоматически с -y)

Советы для полезных ответов:

  • Краткий, но полный - предоставляйте важные детали, не будучи излишне многословным
  • Фокусируйтесь на "почему" - объясняйте рассуждения за вашими изменениями
  • Упоминайте ограничения - отмечайте ограничения или особые соображения
  • Связывайте с внешним контекстом - ссылайтесь на issues, документацию или документы дизайна
  • Пустые ответы допустимы - если вопрос не применим, просто нажмите Enter

Комбинация с другими флагами

Интерактивный режим хорошо работает с большинством других флагов:

# Индексировать все изменения и задавать вопросы
uvx gac -ai

# Задавать вопросы с детальным выводом
uvx gac -i -v

Лучшие практики

  • Используйте для сложных PR - особенно полезно для pull requests, требующих детальных объяснений
  • Командная работа - вопросы помогают вам подумать об изменениях, которые будут проверять другие
  • Подготовка документации - ваши ответы могут помочь сформировать основу для release notes
  • Инструмент обучения - вопросы укрепляют хорошие практики сообщений коммитов
  • Пропускайте для простых изменений - для тривиальных исправлений базовый режим может быть быстрее

Статистика использования

uvx gac отслеживает лёгкую статистику использования, чтобы вы могли видеть свою активность коммитов, серии, использование токенов и наиболее активные проекты и модели. Статистика хранится локально в ~/.gac_stats.json и никогда никуда не отправляется — телеметрии нет.

Что отслеживается: общее количество запусков gac, общее количество коммитов, общее количество токенов промпта и завершения, даты первого и последнего использования, ежедневные и еженедельные счётчики (gac, коммиты, токены), текущая и самая длинная серия, активность по проектам (gac, коммиты, токены промпта + завершения) и активность по моделям (gac, токены промпта + завершения).

Что НЕ отслеживается: сообщения коммитов, содержимое кода, пути к файлам, личная информация или что-либо помимо счётчиков, дат, имён проектов (полученных из git remote или имени каталога) и имён моделей.

Opt-in или Opt-out

uvx gac init спрашивает, хотите ли вы включить статистику, и объясняет, что именно хранится. Вы можете передумать в любое время:

  • Включить статистику: снимите GAC_DISABLE_STATS или установите в false/0/no/off/пусто.
  • Отключить статистику: установите GAC_DISABLE_STATS в truthy-значение (true, 1, yes, on).

При отказе от статистики во время uvx gac init и обнаружении существующего ~/.gac_stats.json, вам будет предложена опция его удаления.

Подкоманды статистики

Команда Описание
uvx gac stats Показать вашу статистику (то же, что uvx gac stats show)
uvx gac stats show Отобразить полную статистику: итоги, серии, ежедневную и еженедельную активность, использование токенов, лучшие проекты, лучшие модели
uvx gac stats models Подробная статистика для всех моделей с разбивкой токенов, скоростью, задержкой и графиками задержки на коммит
uvx gac stats projects Статистика для всех проектов с разбивкой токенов и средним файлов на gac
uvx gac stats recent Последние 10 gac (-n 20 для большего количества), с токенами, скоростью, задержкой и файлами на gac
uvx gac stats reset Сбросить всю статистику до нуля (запрашивает подтверждение)
uvx gac stats reset model <model-id> Сбросить статистику для конкретной модели (без учёта регистра)

Примеры

# Просмотреть общую статистику
uvx gac stats

# Подробная разбивка всех использованных моделей
uvx gac stats models

# Статистика всех проектов
uvx gac stats projects

# Недавняя история gac
uvx gac stats recent -n 20

# Сбросить всю статистику (с запросом подтверждения)
uvx gac stats reset

# Сбросить статистику для конкретной модели
uvx gac stats reset model wafer:deepseek-v4-pro

Что вы увидите

Запуск uvx gac stats отображает:

  • Общее количество gac-запусков и коммитов — сколько раз вы использовали gac и сколько коммитов он создал
  • Текущая и самая длинная серия — подряд идущие дни с активностью gac (🔥 при 5+ днях)
  • Сводка активности — gac-запуски, коммиты и токены за сегодня и эту неделю по сравнению с вашим пиковым днём и пиковый неделей
  • Лучшие проекты — 5 ваших наиболее активных репозиториев по количеству gac + коммитов, со средним файлов на gac и использованием токенов
  • Лучшие модели — 5 ваших наиболее используемых моделей с общей скоростью, задержкой и использованием токенов

Запуск uvx gac stats projects показывает все проекты (не только топ-5) с:

  • Таблица всех проектов — каждый проект, отсортированный по активности, с количеством gac, количеством коммитов, отношением коммитов на gac, средним файлов на gac, токенами промпта, токенами завершения, токенами рассуждений, общими токенами и долей от общего числа gac
  • Столбчатая диаграмма активности — горизонтальные столбцы, показывающие относительное количество gac по проектам
  • Столбчатая диаграмма использования токенов — горизонтальные столбцы, показывающие относительное потребление токенов по проектам

Запуск uvx gac stats models показывает все модели (не только топ-5) с:

  • Таблица всех моделей — каждая использованная модель, отсортированная по активности, с количеством gac, количеством коммитов, общей скоростью (токенов/сек), общей задержкой, токенами промпта, токенами завершения, токенами рассуждений и общими токенами
  • График сравнения скоростей (30д) — горизонтальная столбчатая диаграмма недавних (последние 30 дней) скоростей моделей, отсортированная от самых быстрых к самым медленным, цветовая кодировка по перцентилю скорости (🟡 молниеносно, 🟢 быстро, 🔵 умеренно, 🔘 медленно)
  • График сравнения задержки (30д) — горизонтальная столбчатая диаграмма недавней задержки за вызов, отсортированная от кратчайшей к длиннейшей
  • График задержки на коммит (30д) — горизонтальная столбчатая диаграмма недавней задержки, разделённой на количество коммитов, показывающая реальное время ожидания на коммит (модель, делающая 5 коммитов за 10с gac, стоит 2с/коммит vs модель, делающая 1 коммит за 25с gac при 25с/коммит)
  • Празднование рекордов — 🏆 трофеи при установке новых ежедневных, еженедельных рекордов, рекордов токенов или серии; 🥈 за их повторение
  • Подбадривающие сообщения — контекстуальные напоминания на основе вашей активности

Запуск uvx gac stats recent показывает ваши последние 10 gac-запусков (настраивается с -n):

  • Таблица недавних gac — каждый gac с относительным временем, проектом, моделью, количеством коммитов, файлами, скоростью, задержкой и разбивкой токенов на gac

Отключение статистики

Установите переменную окружения GAC_DISABLE_STATS в truthy-значение:

# Отключить отслеживание статистики
export GAC_DISABLE_STATS=true

# Или в .gac.env
GAC_DISABLE_STATS=true

Falsy-значения (false, 0, no, off, пусто) оставляют статистику включённой — как и при отсутствии переменной.

При отключении gac пропускает всю запись статистики — не происходит чтения или записи файлов. Существующие данные сохраняются, но не будут обновляться, пока вы не включите их снова.

Уведомления через Discord Webhook

gac может уведомлять Discord-канал каждый раз, когда вы делаете коммит, используя URL вебхука из настроек интеграции вашего канала. Интеграция является опциональной: она ничего не делает, пока вы явно не настроите URL вебхука.

Настройка

Используйте dédiated группу подкоманд discord:

uvx gac discord setup     # интерактивно настроить URL вебхука
uvx gac discord show      # показать, настроен ли вебхук (URL замаскирован)
uvx gac discord test      # отправить тестовое уведомление на настроенный вебхук
uvx gac discord remove    # удалить настроенный URL вебхука

Альтернативно, установите переменную напрямую в $HOME/.gac.env（или./.gac.env):

GAC_DISCORD_WEBHOOK_URL='https://discord.com/api/webhooks/XXXX/YYYY'

Поведение

  • Срабатывает после каждого успешного коммита (индивидуальные и групповые рабочие процессы). Пропускается при --dry-run и --message-only.
  • Отправляет встраиваемое сообщение в стиле GitHub с зелёной полосой, репо + ветка как авторская строка, тема коммита как заголовок, тело коммита как описание и короткий SHA в футере.
  • Использует аватар gac и имя пользователя gac.
  • Ошибки вебхука записываются на уровне WARNING и никогда не блокируют ваш коммит.
  • Оставьте GAC_DISCORD_WEBHOOK_URL не установленным（или пустым）для отключения. gac init не затрагивается — настройка Discord находится только в gac discord.

Получение справки