Автодополнение: bash, zsh, fish, powershell

Как только root-команда исполнена, Cobra добавляет к ней команду completion с четырьмя подкомандами: bash, zsh, fish и powershell. Каждая печатает в stdout скрипт автодополнения — длинный, но не ваш: в нём функции конкретного шелла, которые при каждом Tab вызывают вашу же утилиту со скрытой командой __complete и списком уже введённых слов. Бинарник в ответ отдаёт варианты — команды, алиасы, флаги, — и шелл показывает их пользователю. Логика completions живёт в программе, а не в скрипте: добавили подкоманду, поменяли флаг — дополнение обновится на следующем запуске, перегенерировать скрипт заново не обязательно. У каждой подкоманды есть флаг --no-descriptions: подавляет пояснения рядом с вариантами, о нём ниже. Команда completion видна в справке наравне с остальными; если она не нужна — CompletionOptions.DisableDefaultCmd убирает её целиком, а HiddenDefaultCmd оставляет рабочей, но прячет из help.

Bash — самый простой случай, его схема из блока выше закрывает 90% пользователей Linux. Zsh капризнее: скрипт должен лежать в каталоге из массива fpath под именем _notes — с подчёркиванием, совпадающим с именем команды, — а загрузчик функций compinit обязан отработать при старте. Если вы ставили oh-my-zsh, compinit вызывается его init-скриптом автоматически, и автодополнение bash zsh сводится к одной команде записи файла; в голом zsh проверьте, что .zshrc содержит autoload -Uz compinit и compinit, иначе дополнение молча не заведётся — шелл не ругается, просто Tab продолжает предлагать файлы каталога. Fish самый дружелюбный: положили файл в каталог completions — всё, перезапуск не обязателен. Powershell отличается тем, что скрипт исполняется в момент загрузки профиля, поэтому имя бинарника снова должно резолвиться в PATH заранее.

Стоит понимать, за что скрипт отвечает без вашего участия. Подкоманды и их алиасы — да, включая группы и порядок из урока про группы и алиасы. Флаги — да: и локальные, и персистентные, унаследованные с корня, вместе с шорткатами и текстом помощи в описаниях. Значения булевых флагов true и false — тоже. А вот аргументы команд — нет: для них Cobra без ваших функций предложит файлы каталога, как и любой шелл. Поэтому notes show не подскажет имена заметок: для аргументов нужна ValidArgsFunction, тема следующего урока. Третье место, где дополнение умолчит — значения обычных строковых флагов: notes list --format <Tab> не знает, что format бывает json или table, и снова предложит файлы. Всё остальное обновится само при следующем запуске бинаря — перегенерация скрипта нужна только при обновлении самой Cobra.

Печатать скрипт руками — нормальный путь для пользователей. Но у команд, которые распространяются пакетами, есть второй: генерировать дополнение на этапе сборки и класть файлы прямо в пакет — так делает gh и почти всё, что живёт в brew и apt. В Go-коде это те же самые функции, которые стоят за подкомандами: GenBashCompletionV2, GenZshCompletion, GenFishCompletion, GenPowerShellCompletion. Обычно их прячут за служебную команду go generate или собирают отдельным бинарем, потому что в рантайме пользователю это не нужно. Дополнительный плюс генерации при сборке — версия скрипта всегда совпадает с версией бинарника: новая команда, добавленная в релизе, попадёт и в файл дополнения, который уехал в пакет. Как собрать релиз и проставить версии, разбирает урок про сборку и goreleaser.

По умолчанию __complete возвращает варианты вместе с описаниями: notes lis<Tab> подсказывает list с подписью «Показать заметки». Красиво, но не бесплатно: описания едут отдельным полем, и в zsh с сотнями вариантов второй столбец замедляет отрисовку списка и занимает экран. Флаг --no-descriptions на любой подкоманде completion — или DisableDescriptions в CompletionOptions — выключает подписи: останутся только имена. Третий сценарий — приватные утилиты, где описания раскрывают внутренности: путь команд ни к чему чужому глазу. Отдельно держите в голове рассинхрон версий: скрипт, сгенерированный старым бинарем, может не знать новых полей протокола __complete, поэтому правило простое — дополнение устанавливается из той же версии утилиты, которой пользуется человек. Обновили CLI — попросите пользователя перезаписать файл дополнения или обновите его в пакете при сборке.

У bash два поколения скриптов. Новый V2 — тот, что печатает completion bash сегодня: он короче, быстрее и уважает директивы, но рассчитан на bash четвёртой ветки и установленный пакет bash-completion; на CentOS 7 и прочих раритетах его поведение непредсказуемо. Легаси-генератор GenBashCompletion остался для совместимости: скрипт крупнее, описаний не показывает, но работает даже там, куда новый не доезжает. Выбирают так: современные системы — V2, поддержка древних дистрибутивов — легаси. Проверить, что у пользователя, можно по секции bash в справке команды completion — Cobra печатает подсказки по установке с учётом версии генератора. Для fish и powershell таких поколений нет: один скрипт, одна схема установки из таблицы выше.

Скрипт из этого урока подсказывает команды и флаги — но не аргументы: после notes show Tab предложит файлы, а не имена заметок. Это чинит ValidArgsFunction — следующий урок про динамические подсказки из файлов и API. Дополнение — часть «обвязки» CLI наравне с man-страницами: их генерацию разбирает урок про документацию, а упаковку скриптов в релиз — урок про сборку. Обзор курса — на странице Cobra. Практика на закрепление: установите дополнение для своего шелла, скройте completion из справки и проверьте, что Tab подсказывает и подкоманды, и флаги --no-descriptions против обычных.